feat(sec): constrain the conformance CI trigger at admission (R-SEC-02)

Implements the credential model the operator chose for wiring L2/L3 into CI: a narrow trigger SA bounded by a fail-closed Kyverno admission policy, rather than the zero-credential GitOps-native alternative (plan section 4, primary model). THE ESCALATION THIS CLOSES. Kubernetes places NO `use` check on a Job's serviceAccountName. Any principal that can `create jobs` in ns conformance can create a Job running as conformance-runner -- nodes/patch, pods/exec, namespaces/patch -- with an arbitrary command. A CI token with plain `create jobs` IS that privileged identity no matter how narrow its own Role looks. RBAC cannot fix this; only constraining the SHAPE of what the trigger may create can. Adds: * SA/Role/RoleBinding conformance-trigger -- create+get+list+watch jobs, get pods and pods/log, nothing else. Namespaced. No delete (a trigger that can delete can hide a failed run), no exec, no secrets. Results come back as a tarball on stdout read via pods/log, so no execution channel into the runner pod is ever granted. * ClusterPolicy conformance-trigger-job-shape -- Enforce, failurePolicy: Fail. It does NOT use ${KYVERNO_VALIDATION_ACTION}: a security boundary an overlay can downgrade to Audit is not a boundary. It constrains ONLY conformance-trigger, so a mistake here cannot wedge the rest of the cluster. * Flux Kustomization `conformance` -> ./conformance/incluster, wait:false and non-gating like apps-vms, so a test identity can never stall the platform or app tiers. * A kyverno test with seven cases, six of them real escalation paths. VERIFIED by `kyverno apply` (pass: 10, fail: 6, error: 0), not assumed: evil-command DENIED at /spec/template/spec/containers/0/command/ <- THE attack evil-image DENIED at .../image/ tag-not-digest DENIED at .../image/ (mutable tag is republishable) host-namespaces DENIED at /spec/template/spec/hostPID/ extra-volume DENIED by the volumes foreach injected-args DENIED by the args foreach good-run ADMITTED ALSO FIXES A FAIL-OPEN IN THE GATE ITSELF. `kyverno test` does NOT fail when a policy cannot LOAD: every row becomes "Skip / Invalid Policy" and it still prints "N tests passed" and exits 0. Measured while writing this policy -- a schema error (subjects in a separate match.all entry from resources) produced exactly that, and ci/l0.sh would have certified a security policy that does not load as green. This is not specific to this policy: a typo in restrict-host-namespaces or secret-provenance would silently disable it with the gate still green. ci/l0.sh now scans for "Invalid Policy" and fails. Proven: broken policy -> l0 rc=1, restored -> rc=0. IMAGE PINNING, HONEST LIMIT: the plan specifies pinning the exact runner image digest. That image does not exist yet, so this enforces the enforceable half -- the image must be under the conformance repository path AND digest-pinned, never a mutable tag. Residual surface: anyone who can PUSH to that path could publish a different digest. Tighten to the literal digest when the image is built; it is a one-line change to the pattern, reviewed in a PR, which is where a change to a security boundary belongs. NOT YET WIRED, deliberately: no runner image, no trigger kubeconfig, no CLUSTER_AVAILABLE. The identities here are inert until those exist, and PR #12 makes CLUSTER_AVAILABLE=true block rather than fake a green in the meantime. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Merge pull request 'fix(gitea): admins could override the gate' (#10 ) from fix/gitea-admins-could-override-the-gate into main
2026-09-29 03:22:41 -05:00 · 2026-09-29 07:43:52 +00:00 · 2026-09-29 02:36:38 -05:00 · 2026-09-29 07:32:52 +00:00 · 2026-09-29 02:28:55 -05:00 · 2026-09-29 07:22:50 +00:00
243 changed files with 31364 additions and 1430 deletions
@@ -40,9 +40,15 @@ and ADR-0011: **CI holds no broad kubeconfig.** L2/L3 run as an in-cluster **Cha
 *collects* its artifacts, using a narrow trigger credential referenced **by secret name only**
 (`secrets.CONFORMANCE_TRIGGER_KUBECONFIG`) — never a plaintext secret, never a cluster-admin kubeconfig.

-## Honest SKIP — never fake green (Phase 0)
+## Honest SKIP — never fake green

-**No cluster exists in Phase 0.** The gate is deliberately built so unavailable checks **SKIP loudly,
+**NOTE (2026-09-29):** this section is written in the past's voice — "Phase 0", "no cluster
+exists". **A cluster has existed for weeks** and Flux has been reconciling against it. The
+skip logic below is still correct and still honest, but read it as describing a **live
+coverage gap** (L2/L3 is not wired into CI) rather than an expected phase. Its being
+phrased as a phase is part of why the gap went unexamined.
+
+Originally: The gate is deliberately built so unavailable checks **SKIP loudly,
 they do not pass**:

 - The `conformance` job is `if: ${{ vars.CLUSTER_AVAILABLE == 'true' }}` — with no cluster it is
@@ -77,21 +83,29 @@ Both dirs are git-ignored (see [`.gitignore`](../../.gitignore)).
 ## Triggers & branch model (CONTRIBUTING.md)

 - `pull_request` → `main`: **PRs are the enforced merge gate into `main`.**
- `push` → `feature/**`, `fix/**`, `docs/**`, `chore/**`: fast feedback on the branch. **No work on `main`.**
+- `push` → `main` only. The per-branch prefix list was removed: `act_runner` runs at capacity 1,
+  so a branch push fires a redundant run that serialises *ahead* of the PR run for the same tree.
+  **No work on `main`** — and since 2026-09-29 that is enforced, not conventional: `main` is a
+  protected branch and a direct push is rejected by the pre-receive hook (verified, not assumed).

-## Transition: generic-CI-now → Gitea-Actions-after-Gitea-is-up
+## Transition: COMPLETE (2026-09-29)

-Per [`CONTRIBUTING.md`](../../../home-network-k3s/CONTRIBUTING.md) and
-[`docs/05` §"local bootstrap → self-hosted Gitea"](../../../home-network-k3s/docs/05-gitops-and-delivery.md):
+This section used to describe a migration as pending. It has happened. Gitea is live at
+`gitea.home.keithjackson.dev`, the runner `incluster-dind` is registered and online, and
+`gate.yml` runs on every PR.

-1. **Now (interim):** there is **no remote git host** on this network. This workflow file is dormant —
-   but the **identical gate runs locally today** via `make -C ci gate` (R-TEST-02). Development is
-   local feature-branch → `main`, the gate enforced by convention + the local runner.
-2. **Gitea comes online early** (one of the first services onboarded) at `gitea.home.keithjackson.dev`.
-3. **CI moves to Gitea Actions:** this workflow activates unchanged. The only operational steps are
-   enabling a Gitea Actions runner and setting `vars.CLUSTER_AVAILABLE=true` +
-   `secrets.CONFORMANCE_TRIGGER_KUBECONFIG` once a dev/test cluster exists. PRs then become the
-   **platform-enforced** merge gate — the same no-work-in-main rule, now enforced by machine.
+**What took a month to notice:** the migration was recorded as done on 2026-08-31 without
+anyone checking the platform. In reality `main` had **no branch protection** and **zero
+runners were registered** until 2026-09-29. Every "the gate enforces this" statement in
+between rested on an assertion nobody verified. PR #1 — the first pull request this
+repository ever had — sat `pending` for 30.6 minutes because nothing existed to run it.
+
+So: **do not read this file, or the DECISIONS-LOG, as evidence about the live platform.**
+Query the API. `infra/gitea/` holds the scripts and the measured state.
+
+Still genuinely outstanding: `vars.CLUSTER_AVAILABLE` and
+`secrets.CONFORMANCE_TRIGGER_KUBECONFIG` are unset, so L2/L3 conformance does not run in
+CI. That is a real coverage gap, not a phase.

 ## Configuration (set in Gitea; referenced by name only)

@@ -1,40 +1,74 @@
 # .gitea/workflows/gate.yml — the ENFORCED PR merge gate (Phase 6, WS-GITOSS).
 #
 # This is the LIVE gate wired to the in-cluster Gitea Actions runner (ns gitea-actions,
-# Docker executor + DinD). It invokes the AGGREGATE merge gate — `make -C ci gate` — so CI
-# runs BYTE-FOR-BYTE the same command a human runs in the devcontainer (R-TEST-02): the
-# runner just installs the pinned tools from ci/versions.env first. `make -C ci gate`
-# (ci/gate.sh) runs every stage in order — spec-immutability, lint, Kyverno L0,
-# render==golden, L1 offline render — and applies the R-TEST-03 decision, printing
-# "MERGE GATE: PASS" / "MERGE GATE: BLOCKED". It is the single required status check on
-# `main` (see branch protection). A non-zero exit fails the job, so a BLOCKED gate blocks
-# the merge.
+# Docker executor + DinD). It invokes the AGGREGATE merge gate — `./ci/gate.sh`, which is
+# exactly what `make -C ci gate` runs, so CI and the devcontainer gate the same way
+# (R-TEST-02): the runner just installs the pinned tools from ci/versions.env first (and see
+# below for why the script, not `make`, is invoked here). It runs every stage in order —
+# spec-immutability, lint, Kyverno L0, render==golden, L1 offline render — and then applies the
+# R-TEST-03 decision, printing
+# "MERGE GATE: PASS" (0) / "BLOCKED" (1) / "UNDETERMINED" (3) / "NOT APPLICABLE" (0). It is the
+# single required status check on `main` (see branch protection). A non-zero exit fails the job,
+# so a BLOCKED gate blocks the merge.
+#
+# WHY THIS STEP DECLARES GATE_STRICT_SKIPS AND TOLERATES EXIT 3 (2026-09-13). A SKIPPED stage is
+# never green, and since 2026-09-13 gate.sh refuses to print PASS when one did not run (it used to
+# print "— not green" and then "MERGE GATE: PASS", exit 0 — fail-open in the gate itself). Two
+# kinds of non-run must be told apart HERE, in the caller, because only the caller knows which
+# environment it is:
+#   * a pinned tool missing or a seam unwired ON THIS RUNNER is a DEFECT — the toolchain is
+#     installed for us two steps up. GATE_STRICT_SKIPS=true DECLARES that (no env sniffing, no
+#     "does this look like CI?" heuristic) and makes those skips exit 1: untolerated, job fails.
+#   * spec-immutability CANNOT be verified here at all: the spec repo is a separate repo and is
+#     not checked out into this runner (SPEC_REPO_SLUG unwired; blueprint in merge-gate.yaml). It
+#     is the ONLY skip that can still reach exit 3 under strict skips, which is what makes
+#     `|| [ "$?" -eq 3 ]` a narrow, reviewed tolerance rather than a blanket one. The log still
+#     says UNDETERMINED and names R-TEST-06 as unverified. Wire the spec checkout (or set
+#     REQUIRE_SPEC_VERIFICATION=true) and this tolerance should be deleted.
+# Called DIRECTLY, not through `make`: GNU make reports any recipe failure as its own exit 2, so
+# `make -C ci gate || [ "$?" -eq 3 ]` would see 2 and fail the job. Same reason the
+# spec-immutability pre-step below calls the script directly.
 #
 # The cluster-gated L2/L3 conformance stage SKIPS honestly here (exit 3, surfaced not faked
-# — HARD RULE 4) because this runner declares no cluster: `make -C ci gate` does not set
-# CLUSTER_AVAILABLE, so gate.sh reports the touched requirements UNVERIFIED without blocking
-# Phase-0/6 static work. L2/L3 run as an IN-CLUSTER Chainsaw Job (its own scoped SA; CI holds
+# — HARD RULE 4) because this runner declares no cluster: nothing here sets CLUSTER_AVAILABLE,
+# so gate.sh reports the touched requirements UNVERIFIED — and NAMES that declared gap in its
+# PASS headline — without blocking Phase-0/6 static work. L2/L3 run as an IN-CLUSTER Chainsaw Job (its own scoped SA; CI holds
 # no broad kubeconfig) driven by the separate `conformance` job below.
 #
 # NOTE (R-TEST-06 / gate-semantics): spec-immutability is ALSO surfaced as its own explicit
 # early step (below) so its result is a distinct, tolerant status in the Gitea UI; gate.sh
-# re-runs it as its first stage, which is the authoritative one. `make -C ci gate` here is
-# the byte-identical laptop gate; the extra pre-step is a read-only git-diff check and is
+# re-runs it as its first stage, which is the authoritative one. The gate step below is the
+# same script the laptop runs; the extra pre-step is a read-only git-diff check and is
 # purely additive. The full pipeline blueprint (spec-checkout, per-layer jobs, decision job)
 # is retained dormant in merge-gate.yaml.
 ---
 name: gate

+# TRIGGERS — deliberately only `pull_request` into main, plus `push` to main itself.
+#
+# There is NO per-branch push trigger. There used to be a prefix list (feature/** fix/**
+# docs/** chore/**) for "fast feedback on the branch", and it was a net negative here:
+#
+#   * `act_runner` runs at capacity 1. A branch push and its PR fire the SAME gate over the
+#     SAME tree, and the redundant run SERIALISES AHEAD of the PR run — doubling the wall
+#     clock on the one result that actually gates the merge. That cost real time during the
+#     2026-09-29 plex claim, where the loop is racing a short-lived token.
+#   * The list silently did not match this repo's own convention. Branches here are `feat/**`,
+#     which was absent, so the "fast feedback" never fired for the most common prefix anyway —
+#     a mismatch nobody noticed for a month because its only symptom was a MISSING run.
+#     Any hand-maintained prefix list has that failure mode; deleting it removes the class.
+#   * It is redundant. CLAUDE.md already requires `./ci/gate.sh` in the pinned toolbox before
+#     you push (74s locally), and the PR gate re-runs it authoritatively. A third run of the
+#     same checks buys nothing.
+#
+# `push: [main]` is KEPT: post-merge main must still be verified, and it is the only run for
+# which no PR context exists.
 on:
  pull_request:
    branches: [main]
  push:
    branches:
      - main
-      - 'feature/**'
-      - 'fix/**'
-      - 'docs/**'
-      - 'chore/**'

 concurrency:
  group: gate-${{ github.ref }}
@@ -69,13 +103,17 @@ jobs:
      - name: Spec immutability (R-TEST-06, skips if spec repo absent)
        run: ./ci/spec-immutability.sh || [ "$?" -eq 3 ]

-      # Aggregate merge gate: byte-for-byte the command a human runs in the devcontainer
-      # (`make -C ci gate` -> ci/gate.sh). Runs spec-immutability, lint, Kyverno L0,
-      # render==golden and L1 render, then the R-TEST-03 decision. Exits non-zero on a
-      # BLOCKED gate, which fails this job. The cluster-gated L2/L3 stage SKIPS here (no
-      # CLUSTER_AVAILABLE) — surfaced as UNVERIFIED, never faked green (see header).
-      - name: Merge gate — make -C ci gate
-        run: make -C ci gate
+      # Aggregate merge gate: the same script a human runs in the devcontainer via
+      # `make -C ci gate`. Runs spec-immutability, lint, Kyverno L0, render==golden and L1
+      # render, then the R-TEST-03 decision. Exits non-zero on a BLOCKED gate, which fails this
+      # job. The cluster-gated L2/L3 stage SKIPS here (no CLUSTER_AVAILABLE) — surfaced as
+      # UNVERIFIED and NAMED in the PASS headline, never faked green. GATE_STRICT_SKIPS + the
+      # tolerated exit 3 are explained in the file header; the tolerance covers exactly one
+      # thing, the unverifiable spec repo, and nothing else can produce a 3 here.
+      - name: Merge gate — ci/gate.sh (what `make -C ci gate` runs)
+        env:
+          GATE_STRICT_SKIPS: "true"
+        run: ./ci/gate.sh || [ "$?" -eq 3 ]

      # NOTE: no actions/upload-artifact step. Gitea Actions rejects upload-artifact@v4
      # ("not supported on GHES" — Gitea does not implement the artifact-v2 backend), which
@@ -11,11 +11,14 @@
 #                                          v
 #                                     merge-gate decision  [R-TEST-03: touched subset green]
 #
-# Transition (CONTRIBUTING.md / docs/05 §"local bootstrap -> self-hosted Gitea"):
-# Today there is no Gitea host, so this file is dormant. The SAME gate is runnable
-# now via `make -C ci gate` (R-TEST-02). Once Gitea is self-hosted and Gitea
-# Actions is enabled, this workflow becomes the ENFORCED PR merge gate into main —
-# no code change required, only turning on the runner and setting CLUSTER_AVAILABLE.
+# STATUS (corrected 2026-09-29): Gitea IS hosted and Gitea Actions IS enabled; the runner
+# `incluster-dind` is online and gate.yml is the live PR gate. The text that used to sit here
+# ("Today there is no Gitea host, so this file is dormant") was stale by weeks -- it was written
+# as a plan and never revisited once the plan completed.
+#
+# THIS file is still dormant, but for the reason in the DORMANT block below -- its spec checkout
+# and L2/L3 seams are unwired -- NOT because there is no host. Do not read a stale plan as a
+# statement about the live platform; query the API instead (see infra/gitea/).
 #
 # CI holds NO broad kubeconfig. L2/L3 run as an in-cluster Chainsaw Job whose own
 # scoped ServiceAccount holds cluster access (docs/14, R-SEC-02); CI uses only a
@@ -39,6 +39,21 @@ install_chainsaw() {
  curl -fsSL "$url" | tar -xz -C "$bindir" chainsaw
 }

+# promtool — the alert-rule UNIT-TEST engine the L0 check
+# conformance/tests/l0-static/alert-rules-unit-tested runs. Installed for the l0 stage because
+# without it that check exits 3 (SKIPPED, never green) on the runner and the alert unit tests
+# would be enforced nowhere — the exact "coverage that looks present" failure it exists to end.
+# Pinned from ci/versions.env to the Prometheus version prod runs (promtool IS the rule engine);
+# the check asserts `promtool --version` equals that pin, so a drifted install FAILS, not skips.
+install_promtool() {
+  have promtool && return 0
+  log "promtool ${PROMTOOL_VERSION} (from the prometheus release tarball)"
+  local tarball="prometheus-${PROMTOOL_VERSION}.${os}-${arch}"
+  curl -fsSL "https://github.com/prometheus/prometheus/releases/download/v${PROMTOOL_VERSION}/${tarball}.tar.gz" \
+    | tar -xz -C "$bindir" --strip-components=1 "${tarball}/promtool"
+  chmod +x "${bindir}/promtool"
+}
+
 install_kubectl() {
  have kubectl && return 0
  log "kubectl ${KUBECTL_VERSION}"
@@ -50,10 +65,10 @@ have() { command -v "$1" >/dev/null 2>&1; }

 case "$stage" in
  lint)        install_yamllint ;;
-  l0)          install_yamllint; install_check_jsonschema; install_kyverno ;;  # schema (check-jsonschema) + Kyverno L0
+  l0)          install_yamllint; install_check_jsonschema; install_kyverno; install_promtool ;;  # schema (check-jsonschema) + Kyverno L0 + alert unit tests
  l1)          install_chainsaw ;;              # L1 render via conformance runner (Chainsaw)
  conformance) install_chainsaw; install_kubectl ;;   # trigger the in-cluster Job
-  all)         install_yamllint; install_check_jsonschema; install_kyverno; install_chainsaw; install_kubectl ;;
+  all)         install_yamllint; install_check_jsonschema; install_kyverno; install_promtool; install_chainsaw; install_kubectl ;;
  *) echo "unknown stage: $stage" >&2; exit 2 ;;
 esac
 log "stage '${stage}' tools ready"
@@ -0,0 +1,97 @@
+# RECOVERY BASELINE — the COMPLETE Cloudflare record set for zone `keithjackson.dev`
+# as it stood IMMEDIATELY BEFORE feat/externaldns-scope-public-only is applied.
+#
+# WHY THIS FILE EXISTS. The branch that adds it changes which resources ExternalDNS considers,
+# and ExternalDNS runs `policy: sync` — a record whose source stops matching is DELETED, not
+# merely left alone. That is a one-way, outward-facing operation against a live authoritative
+# zone, so the pre-state is captured and committed BEFORE the change lands, and any record the
+# reconcile removes can be restored by hand from this file. It is the same discipline as
+# dns-before.txt / dns-verify.txt / dns-post-l2.txt beside it, applied to a destructive-capable
+# change rather than to a migration.
+#
+# CAPTURED 2026-09-14 from the Cloudflare API (GET /zones/<id>/dns_records, all pages) using the
+# SOPS-encrypted token in platform/externaldns/cloudflare-api-token.sops.yaml. Read at the
+# AUTHORITY, not through a resolver: 1.1.1.1 served stale answers for minutes after the
+# 2026-09-13 apex flip and must not be trusted for this. `dig` is on the host but NOT in the
+# devcontainer, which has previously produced false "no records" readings — the API is the only
+# reading that is both complete and authoritative.
+#
+# FORMAT (5 fields, `|`-separated) — wider than the sibling files on purpose: a restore needs the
+# TTL and the proxy flag, not just the value.
+#
+#   <type>|<name>|<content>|<ttl>|<proxied>
+#
+# ttl 1 = Cloudflare "Automatic". proxied false = DNS-only (grey cloud), which every record here
+# is; a restore that flips one to proxied would put Cloudflare's edge in front of a LAN address.
+#
+# 39 records. 36 of them are ExternalDNS-managed (18 A + their 18 `a-`-prefixed TXT registry
+# entries), every one registered `external-dns/owner=prod` — i.e. THIS cluster owns them, which
+# is why this cluster's reconcile is able to delete them. The remaining 3 belong to the legacy
+# non-k3s stack and carry NO TXT registry entry, so no owner id claims them and ExternalDNS
+# cannot touch them regardless of what this branch does:
+#
+#   *.keithjackson.dev            -> 136.51.115.252   legacy stack (the zone wildcard)
+#   brickbreak.keithjackson.dev   -> 20.236.242.14    unrelated, off-prem
+#   dev.brickbreak…               -> 20.236.242.14    unrelated, off-prem
+#
+# NOTE there is NO `*.home.keithjackson.dev` wildcard in the zone any more (the comment in
+# clusters/prod/kustomization.yaml still says the zone has both wildcards; it does not, as of
+# this capture). A single-label wildcard does not match two labels, so `*.keithjackson.dev` does
+# NOT cover `<svc>.home.keithjackson.dev`: when a specific `<svc>.home` record is removed, that
+# name goes to NXDOMAIN publicly rather than falling back to the legacy IP. That is the intended
+# end state for `internal` services and it is also precisely why Pi-hole must already be
+# answering the LAN authoritatively before this branch merges.
+#
+# WHICH OF THESE THIS BRANCH DELETES — the 12 rows for the six `exposure: internal` catalog
+# services (jackett, pihole, qbittorrent, radarr, semaphore, sonarr): each one's A record and its
+# `a-`-prefixed TXT registry entry. Nothing else. Verified live on prod against the deployed
+# v0.21.0 with a throwaway hostname before any of this was authored: adding the annotation to an
+# HTTPRoute that already had a published record produced
+# `action=DELETE record=... type=A` and `action=DELETE record=a-... type=TXT` one reconcile
+# interval (~60s) later, and nothing else in the zone moved.
+#
+# TO RESTORE ONE ROW BY HAND (both halves, or ExternalDNS will not recognise the record as its
+# own): recreate the A record with its value/ttl/proxied from this file, then recreate the
+# matching `a-<name>` TXT with its content VERBATIM — the `heritage=…,external-dns/owner=prod,
+# external-dns/resource=…` string is what re-establishes ownership. An A record restored without
+# its TXT is unowned and will not be reconciled; a TXT restored with a wrong `resource=` value
+# points the registry at a source object that does not exist.
+A|*.keithjackson.dev|136.51.115.252|1|false
+A|auth.home.keithjackson.dev|192.168.2.20|1|false
+A|brickbreak.keithjackson.dev|20.236.242.14|1|false
+A|crafty-mc.home.keithjackson.dev|192.168.2.22|1|false
+A|crafty.home.keithjackson.dev|192.168.2.20|1|false
+A|dev.brickbreak.keithjackson.dev|20.236.242.14|1|false
+A|gitea.home.keithjackson.dev|192.168.2.20|1|false
+A|grafana.home.keithjackson.dev|192.168.2.20|1|false
+A|headlamp.home.keithjackson.dev|192.168.2.20|1|false
+A|home.keithjackson.dev|192.168.2.20|1|false
+A|jackett.home.keithjackson.dev|192.168.2.20|1|false
+A|keycloak.home.keithjackson.dev|192.168.2.20|1|false
+A|nextcloud.home.keithjackson.dev|192.168.2.20|1|false
+A|pihole.home.keithjackson.dev|192.168.2.20|1|false
+A|plex.home.keithjackson.dev|192.168.2.20|1|false
+A|qbittorrent.home.keithjackson.dev|192.168.2.20|1|false
+A|radarr.home.keithjackson.dev|192.168.2.20|1|false
+A|seerr.home.keithjackson.dev|192.168.2.20|1|false
+A|semaphore.home.keithjackson.dev|192.168.2.20|1|false
+A|sonarr.home.keithjackson.dev|192.168.2.20|1|false
+A|unifi.home.keithjackson.dev|192.168.2.21|1|false
+TXT|a-auth.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/oauth2-proxy/oauth2-proxy"|1|false
+TXT|a-crafty-mc.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=service/crafty/crafty-l4-tcp"|1|false
+TXT|a-crafty.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/crafty/crafty"|1|false
+TXT|a-gitea.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/gitea/gitea-3000"|1|false
+TXT|a-grafana.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/monitoring/grafana"|1|false
+TXT|a-headlamp.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/headlamp/headlamp"|1|false
+TXT|a-home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/homepage/homepage"|1|false
+TXT|a-jackett.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/jackett/jackett-9117"|1|false
+TXT|a-keycloak.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/keycloak/keycloak"|1|false
+TXT|a-nextcloud.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/nextcloud/nextcloud-80"|1|false
+TXT|a-pihole.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/pihole/pihole-80"|1|false
+TXT|a-plex.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/plex/plex-32400"|1|false
+TXT|a-qbittorrent.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/qbittorrent/qbittorrent-8080"|1|false
+TXT|a-radarr.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/radarr/radarr-7878"|1|false
+TXT|a-seerr.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/seerr/seerr-5055"|1|false
+TXT|a-semaphore.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/semaphore/semaphore-3000"|1|false
+TXT|a-sonarr.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=httproute/sonarr/sonarr-8989"|1|false
+TXT|a-unifi.home.keithjackson.dev|"heritage=external-dns,external-dns/owner=prod,external-dns/resource=service/unifi/unifi-l4-tcp"|1|false
@@ -0,0 +1,147 @@
+# CLAUDE.md — how work lands in this repo
+
+Read this before doing anything durable. It is the delivery contract for AI coding
+sessions and agents. `DECISIONS-LOG.md`'s last entry is the current PM handoff and
+takes precedence on *what* to work on; this file governs *how* it lands.
+
+## 1. Never push to `main`. Ever.
+
+Every durable change reaches `main` exactly one way:
+
+    branch  ->  push the branch  ->  open a PR  ->  CI gate green  ->  human approval  ->  merge
+
+There is no other path. Specifically:
+
+- **Do not `git push origin main`.**
+- **Do not `git push origin HEAD:main`.** Same thing wearing a hat.
+- **Do not merge your own PR.** A human approves and clicks merge.
+- **Do not `kubectl apply` / `edit` / `patch` a durable change.** Flux reconciles `main`;
+  anything applied by hand is drift that the next reconcile reverts or, worse, adopts.
+
+> **Many runbooks under `runbooks/` still say `git push origin main` IS the deploy.**
+> That wording is **stale** — it predates the PR flow. It describes what Flux does
+> (main is what the cluster follows), not what you are permitted to do. Honour this
+> file, not that line. Fixing those runbooks is tracked work.
+
+## 2. Enforcement (as of 2026-09-29: the rule is now MACHINE-ENFORCED)
+
+Verified against the live Gitea on 2026-09-29:
+
+| Expected | Actual |
+|---|---|
+| `main` protected, direct push rejected | ✅ `protected: true`, `user_can_push: false` — **verified by a real rejected push**, not by the API's word |
+| PR blocked until the gate passes | ✅ `enable_status_check: true`, context `gate / gate (pull_request)` |
+| Gate runs on every PR | ✅ runner `incluster-dind` online; ~1m35s |
+| Approval required before merge | ✅ `required_approvals: 1` |
+
+All four were FALSE as recently as 2026-09-29, while this repo's own log asserted they were
+true. They are true now because each was measured, and the push rejection was provoked rather
+than assumed. **Re-measure before relying on any of them** — see §2b.
+
+Still not covered: `vars.CLUSTER_AVAILABLE` is unset, so **L2/L3 conformance does not run in
+CI**. A green PR therefore proves the L0/L1 offline subset, not runtime behaviour.
+
+**Consequence for you:** CI now runs, but it does not yet *block* anything. Always run
+the toolbox gate yourself and quote its numbers. Never describe a PR as "green" on the
+strength of a check you have not seen report — and note that a **skipped** Gitea job
+reports as `success`, so a green tick is not by itself evidence that anything ran.
+
+## 2b. Never infer platform state from this repository
+
+**This repo is not evidence about the live platform.** Neither is `DECISIONS-LOG.md`.
+Both describe what someone believed at the time of writing, and both have been
+confidently wrong for a month at a stretch.
+
+On 2026-09-29 the log stated the merge gate was a required status check with a runner
+online. The API said `branch_protections: []` and **zero** runners. Everything downstream
+of that belief — "the gate enforces this", "your push would be rejected", "CI covers it" —
+was wrong, and nothing in the tree could have revealed it, because the tree was the source
+of the error.
+
+**So, before asserting that any gate, protection, runner, secret, or workload is in a
+given state: query the thing itself.**
+
+| Claim about... | Check |
+|---|---|
+| branch protection / required checks | `GET /api/v1/repos/{owner}/{repo}/branches/main` |
+| a runner exists | `GET /api/v1/admin/actions/runners` |
+| CI actually ran | the commit's `/statuses` — and read the **description**; a *skipped* Gitea job reports `success` with "Has been skipped" |
+| a workload / Secret / env | `kubectl --context k3s-prod ...` (read-only is fine for agents) |
+| Flux applied your commit | compare `.status.lastAppliedRevision` against the GitRepository's artifact revision |
+
+Quote the measured field, not the prose. If you cannot measure it, say so explicitly —
+"unverified" is a legitimate report, and a far better one than a confident guess that
+matches the docs.
+
+**A green tick is not proof anything ran.** Read what actually executed.
+
+## 3. Gate before you push
+
+    ./infra/devcontainer/dev.sh run bash -c './ci/gate.sh'
+
+Exit codes are a contract — do not flatten them:
+
+| rc | Meaning |
+|---|---|
+| 0 | PASS |
+| 1 | BLOCKED — something failed |
+| 3 | UNDETERMINED — a stage did not run. **Never report this as green.** |
+
+`spec-immutability` reaches rc 3 whenever the sibling spec repo is not checked out
+beside this one; that single skip is expected and tolerated. Any *other* skip is a
+real gap in your run.
+
+**Never gate on the host.** `promtool` and `kustomize` are not on the host `$PATH`,
+so checks SKIP and you get a false rc 3. Only the pinned toolbox result counts.
+
+### Running the gate from a git worktree
+
+Two unrelated failures, both with known workarounds — put both in any agent brief:
+
+1. **`dev.sh` refuses to start:** `infra/ansible/.cache/prod.kubeconfig` is untracked
+   and exists only in the main checkout. Do **not** copy it (it is a credential).
+   Use `DEV_KUBECONFIG=/dev/null` — the gate contacts no cluster, so L2/L3 scaffold-skip
+   normally.
+2. **Every `git` call inside the container fails:** a worktree's `.git` is a pointer to a
+   gitdir outside the mounted root. `dev.sh` takes no extra-mount flag, so inject one via
+   the `ENGINE` hook — a shim that intercepts `run` and re-execs
+   `podman run -v /path/to/main/.git:/path/to/main/.git:ro "$@"`. A traceback in
+   `tracked_files()` is this bug, not a broken tree.
+
+## 4. Branch naming
+
+Use `feat/`, `fix/`, `docs/`, `chore/`. Note that `.gitea/workflows/gate.yml`'s **push**
+trigger lists `feature/**` — not `feat/**` — so branch pushes get no fast-feedback run.
+The `pull_request` trigger fires regardless of branch name, so the PR gate is unaffected.
+
+## 5. Cluster access
+
+`kubectl` does not work on the operator workstation; the toolchain lives only in the
+pinned container. Always name the context explicitly:
+
+    ./infra/devcontainer/dev.sh run bash -c 'kubectl --context k3s-prod get nodes'
+
+`dev.sh` merges both clusters and picks a current-context **per invocation**; that
+default has already changed once. Never rely on it. Do not run two `dev.sh`
+invocations concurrently.
+
+**Mutating `kubectl` and `flux reconcile` are operator actions, not agent actions.**
+
+## 6. Secrets
+
+- **Never `sops -d` a file into a terminal, a log, or a transcript.**
+- **Never print a Secret's `.data`/`.stringData`** when checking whether it exists —
+  list key names or object names only. A password has been leaked into a transcript
+  this way before.
+- Encrypted files are `*.sops.yaml` or live under `secrets/`. The root `.sops.yaml` is
+  the single creation-rules file; do not add a second one in a subtree.
+- A short-lived credential (e.g. a plex.tv claim token, ~minutes) cannot survive the PR
+  flow. Do not design around committing one — read the expiry from the issuing page and
+  treat a burnt token as free to retry.
+
+## 7. Before you finish
+
+Append a handoff entry to `DECISIONS-LOG.md` describing what you changed, what you
+verified, and what you did **not** verify. State gaps plainly — an honest
+"UNVERIFIED" is worth more than an optimistic "green", and this repo has already been
+burned by the difference.
@@ -38,22 +38,56 @@ ci/             the gate as scripts (lint · schema · Kyverno L0 · L1 render

 ## Status

-Roadmap phases **0–6 are delivered and deployed** on the dev cluster; **Phase 7 (prod) is not
-open** — `clusters/prod` is a design-only overlay.
+Roadmap phases **0–6 are delivered**, and **Phase 7 (Production Readiness) is OPEN and in
+progress**. `clusters/prod` is no longer a design-only overlay: prod is the live cluster, serving the
+apex `home.keithjackson.dev`. The dev cluster was **decommissioned on 2026-09-12** (full migration:
+dev out, prod onto the apex — see the DECISIONS-LOG), so phases 0–6 are now exercised on prod
+hardware rather than on Proxmox VMs.
+
+**Phase 7 exit criteria** — *prod runs the same config via the prod overlay; DR proven; monitoring +
+alerts live*:
+
+| criterion | state |
+|---|---|
+| prod runs the prod overlay | **met** — 3× mini-PC bare metal, one Flux tree, prod overlay only |
+| monitoring + alerts live | **met 2026-09-13** — see the note below; this was not true before that date |
+| **DR proven** | **R-STATE-03 PROVEN on prod 2026-09-14** — off-cluster restore from Cloudflare R2. `R-STATE-02` (node-loss) is still dev-only |
+
+**DR restore is proven on prod.** `R-STATE-03` reads `proven` in `--status` as of 2026-09-14 —
+the first requirement in this repo to reach that state. Both of its verifiers are recorded:
+`dr-restore` (L3, run `20260914T021505Z-24b8111`, sentinel `DR_RESTORED_FROM_OFF_CLUSTER_BACKUP_OK`)
+and `placeholder-guard-coupling` (L0). The L3 drill seeds a canary on the replicated `longhorn`
+class, backs the namespace and volume data up off-cluster, **destroys every in-cluster copy**
+(namespace, PVC and PV), restores into a clean namespace, and asserts the restored PVC binds a
+*different* PersistentVolume — so an in-cluster survival cannot pass as a restore.
+
+**What remains for Phase 7:** `R-STATE-02` (`node-loss`) is still proven only on the decommissioned
+dev cluster. That drill takes a real node down on a live cluster, so it is a deliberate, scheduled
+exercise rather than something to run in passing.
+
+Read `--coverage-only` and `--status` as two different questions; the earlier `PROVEN: 0` was not a
+bug but the honest answer, because proofs are claims about a specific tree on a specific cluster.

 | Phase | Delivered |
 |---|---|
 | 0 Foundations | ServiceDefinition schema + renderer, Kyverno L0 gate, conformance harness, CI |
-| 1 Cluster bring-up | 3-node k3s HA on **Proxmox VE** (`192.168.1.50/.51/.52`), Cilium, Flux, SOPS |
-| 2 Platform core | Cilium · Longhorn · cert-manager (LE-prod wildcard) · ExternalDNS · Gateway API · split-horizon CoreDNS |
+| 1 Cluster bring-up | 3-node k3s HA, embedded etcd, kube-vip VIP, Cilium, Flux, SOPS. Originally Proxmox VMs; **now 3× mini-PC bare metal** (`k3s-prod-1/2/3`, `192.168.2.10/.11/.12`, k3s v1.36.4+k3s1, Debian 13) |
+| 2 Platform core | Cilium · Longhorn · cert-manager (LE-prod wildcard) · ExternalDNS · Gateway API · split-horizon DNS, **both halves**: CoreDNS for pods, and **PiHole as the authoritative LAN resolver** for `${BASE_DOMAIN}` on udp/53 + tcp/53 at a pinned VIP (`192.168.2.23` on prod). The LAN half was claimed from the start but did not exist until 2026-09-14 — PiHole's Service was ClusterIP :80/:4180, so LAN clients ran on hand-maintained per-client `dnsmasq` files |
 | 3 Egress / VPN | ADR-0015 node-level OpenVPN split-tunnel + Cilium egress-gateway steering + host kill-switch |
-| 4 Observability | kube-prometheus-stack · Loki · Alloy · Alertmanager. **Velero still blocked on OQ-BKP**; image-automation authored but disabled |
+| 4 Observability | kube-prometheus-stack · Loki · Alloy · Alertmanager. **Velero unblocked 2026-09-13** — backs up to Cloudflare R2 (OQ-BKP closed; the `velero-plugin-for-aws` tagging incompatibility needed a pinned plugin). Longhorn has **no** backup target by decision: volume data is protected by Velero + kopia to R2. image-automation authored but disabled |
 | 5 IaaS | KubeVirt + CDI on real nested KVM; live-migratable RWX VM storage. The UniFi VM runs, but **UniFi OS Server is not yet installed in the guest** |
 | 6 Identity + CI | Keycloak (Operator + CNPG) · oauth2-proxy forward-auth · Grafana OIDC · **kubectl OIDC SSO with group→RBAC** · in-cluster Gitea Actions merge gate |
+| **7 Production readiness** | **IN PROGRESS** (DR restore proven 2026-09-14; node-loss outstanding). Prod live on bare metal serving the apex; dev decommissioned; CNPG HA 3 instances with primaries spread one per node; NFS bulk media + legacy Nextcloud mounted; VPN egress on prod. Alerting made real 2026-09-13 (Longhorn, cert-manager, Flux and twelve app SLIs had all been unable to fire). **Open: `node-loss` (R-STATE-02) re-proven on prod.** |

-**Conformance: 36 / 51 requirements covered (70.6%)**, 15 gaps, 1 safety-critical gap
-(`R-STATE-02`, Longhorn node-loss). Regenerate with `./conformance/run.sh --coverage-only`;
-the full report is `conformance/_artifacts/coverage/coverage.md`.
+**Conformance: 51 / 51 requirements covered (100%)**, 0 gaps, 0 safety-critical gaps (closed
+2026-09-13; `R-C2-01`/`R-C2-02` were the last two). Regenerate with
+`./conformance/run.sh --coverage-only`; the full report is
+`conformance/_artifacts/coverage/coverage.md`.
+
+Coverage is **not** proof. A requirement is *covered* when an executable test exists for it, and
+*PROVEN* only when a recorded run of that test is in `conformance/runs/ledger.jsonl` at the current
+SHA on the cluster it claims. Read both numbers: `--coverage-only` for the first, `--status` for the
+second.

 The running narrative — decisions, root causes, incidents, follow-ups — is
 [`DECISIONS-LOG.md`](DECISIONS-LOG.md). It, not this table, is the authoritative record.
@@ -41,10 +41,41 @@ spec:
      # disk KubeVirt cannot migrate and eviction would hard-stop the guest.
      evictionStrategy: LiveMigrate
      domain:
+        # =====================================================================================
+        # FIRMWARE UUID == THE CLOUD-INIT INSTANCE-ID. THIS IS THE RE-RUN LEVER. READ BEFORE EDIT.
+        # =====================================================================================
+        # MEASURED on prod 2026-09-14, not assumed:
+        #   * the NoCloud seed KubeVirt builds for this VM carries
+        #       {"instance-id":"de5c3338-6d32-4956-89d1-12c8272b2c07","local-hostname":"unifi"}
+        #     (read out of noCloud.iso inside virt-launcher-unifi-gp594), and that value was
+        #     EXACTLY `spec.template.spec.domain.firmware.uuid`, which KubeVirt's mutating webhook
+        #     had stamped onto the VM OBJECT — so it is PERSISTENT, not per-VMI (the VMI's own uid
+        #     was b532fd7c-…, a different value). It is not a hash of the VM name either: the four
+        #     standard uuid5 namespaces over "unifi" / "unifi.unifi" all produce something else.
+        #   * cloud-init's NoCloud datasource decides "is this the same instance?" by comparing the
+        #     cached instance-id against the guest's DMI product_uuid — which IS this firmware UUID.
+        #
+        # CONSEQUENCE, and it is the whole reason the previous unattended attempt could never have
+        # worked: EDITING `userData` BELOW AND RESTARTING THE VM CHANGES NOTHING. cloud-init sees an
+        # unchanged instance-id, restores its CACHED datasource, never re-reads the seed, and skips
+        # every per-instance module (write_files, runcmd). The new payload is silently ignored.
+        #
+        # So the UUID is pinned HERE, in git, and BUMPING IT IS THE SUPPORTED WAY to make the guest
+        # process a new cloud-init payload: change the trailing hex, commit, restart the VM. Pinning
+        # it also makes a rebuild reproducible — a fresh apply would otherwise take a random
+        # webhook-generated UUID and give the guest a different identity every time.
+        #
+        # The value below is DELIBERATELY NOT the de5c3338-…c07 the live guest booted with: that
+        # difference is what makes the next boot a NEW cloud-init instance and installs the
+        # `install-uos` helper + its systemd unit. `serial` is pinned to the value the webhook
+        # already stamped, so this change does not also churn the guest's DMI serial.
+        firmware:
+          uuid: "de5c3338-6d32-4956-89d1-12c8272b2c11"
+          serial: "24bb12ac-d311-45f6-a75b-90a9e1b63e18"
        # FLAG (verify-at-bringup): Ubuntu 24.04 amd64 cloud images are hybrid BIOS+UEFI bootable,
        # so KubeVirt's default SeaBIOS SHOULD boot cleanly (unlike the Fedora containerdisk, which
-        # is UEFI-only and needed an explicit efi block). If the guest drops to emergency/no-boot,
-        # add:  firmware: { bootloader: { efi: { secureBoot: false } } }
+        # is UEFI-only and needed an explicit efi block). RESOLVED at bring-up: boots as shipped;
+        # the guest reports Ubuntu 24.04.4 LTS.
        cpu:
          cores: 2
        memory:
@@ -58,9 +89,28 @@ spec:
            - name: cloudinit
              disk:
                bus: virtio
+            # The operator's installer URL (+ optional SSH key), delivered as a tiny read-only
+            # iso9660 disk — see the `uosdata` volume near the bottom of this file.
+            - name: uosdata
+              disk:
+                bus: virtio
          interfaces:
+            # MAC PINNED 2026-09-18, and this is a root-cause fix, not cosmetics.
+            # KubeVirt generates a fresh MAC for every VMI when none is pinned. cloud-init writes
+            # /etc/netplan/50-cloud-init.yaml with a `match` on the MAC it saw, and it will NOT rewrite
+            # that file while the NoCloud instance-id is unchanged — and the instance-id here is
+            # domain.firmware.uuid, which is stable across restarts by design. So each VMI recreation
+            # handed the guest a NEW MAC that the retained netplan did not match, leaving enp1s0
+            # administratively DOWN with no address and no DHCP attempt.
+            # That is exactly what the evidence shows for the boot of 2026-09-12: cloud-init's own
+            # device table reports `enp1s0 | Up: False | Address: .`, no apt failures are logged
+            # (because the per-instance modules were skipped), yet UOS is installed and
+            # qemu-guest-agent runs — both of which required a working network on an EARLIER VMI.
+            # Pinning the MAC to the value the current VMI already holds makes the guest's netplan
+            # match permanently, so this cannot recur on the next recreation.
            - name: default
              masquerade: {}
+              macAddress: a6:d7:c0:b3:72:fa
              # Declaring ports on a masquerade iface (a) restricts pod->VM forwarding to exactly
              # these and (b) surfaces them as containerPorts on the virt-launcher pod so the
              # LoadBalancer Services + CiliumNetworkPolicy ingress can target/match them.
@@ -83,41 +133,112 @@ spec:
        - name: rootdisk
          dataVolume:
            name: unifi-rootdisk
+        # =====================================================================================
+        # THE OPERATOR'S ONE FIELD — SOPS Secret `unifi-uos-installer`, delivered as a DISK.
+        # =====================================================================================
+        # KubeVirt exposes a Secret as a small read-only iso9660 disk whose volume label we choose;
+        # each Secret key becomes a file on it. The guest mounts it by label (LABEL=UOSDATA) and
+        # reads `installer-url` plus an optional `console-password`. The Secret ships ENCRYPTED with
+        # REPLACE-ME placeholders, and the guest-side script treats anything that is not an https
+        # URL as "not provided yet" and exits 0 — so the VM boots and stays healthy until the
+        # operator fills it in. See unifi-uos-installer.sops.yaml.example next to this file.
+        #
+        # `console-password` exists because THERE IS CURRENTLY NO WAY INTO THIS GUEST. The stock
+        # Ubuntu cloud image ships a locked `ubuntu` account, this cloud-init never installed a key,
+        # and SSH could not help anyway: the masquerade interface above forwards ONLY the declared
+        # ports, and 22 is not one of them — probed from inside virt-launcher on 2026-09-14, the
+        # guest answers RST on 22 exactly as it does on the UniFi ports. The serial console is the
+        # only door, and a console needs a password. Set it and `virtctl -n unifi console unifi`
+        # works; `kubectl -n unifi logs virt-launcher-unifi-… -c guest-console-log` already gives
+        # read-only console output with no virtctl at all.
+        #
+        # WHY A SEPARATE DISK AND NOT `cloudInitNoCloud.secretRef` (which would also lift the
+        # 2048-byte inline cap): secretRef moves the ENTIRE cloud-config into ciphertext. Two
+        # concrete costs. (a) The shell below stops being reviewable in a diff and falls outside the
+        # L0 dollar-collapse guard, which can only read plaintext. (b) Flux runs its postBuild
+        # envsubst over the DECRYPTED resources, so the escape contract in
+        # clusters/base/apps-vms.yaml would still govern text nobody can see in git — the exact
+        # shape of the 2026-09-13 nextcloud-db incident. Keeping the script in plaintext and putting
+        # ONLY the operator's two values behind SOPS keeps both properties.
+        #
+        # A CHANGED SECRET REACHES THE GUEST ON THE NEXT VMI START with NO firmware-UUID bump: the
+        # disk is rebuilt from the Secret every time the VMI starts, and the systemd unit below
+        # re-reads it on EVERY boot instead of relying on cloud-init (which will not re-run — see
+        # the firmware block above). The UUID bump is a ONE-TIME step, to get that unit installed.
+        - name: uosdata
+          secret:
+            secretName: unifi-uos-installer
+            volumeLabel: UOSDATA
        - name: cloudinit
          cloudInitNoCloud:
-            # INLINE (kept < KubeVirt's 2048-byte userData limit — so NO SSH key here; add one back via
-            # userDataSecretRef only if needed). qemu-guest-agent gives the KubeVirt AgentConnected
-            # signal (proves cloud-init ran); install-uos resolves the latest UOS linux-x64 build from
-            # Ubiquiti's PUBLIC firmware API (no auth) and installs it non-interactively (UI on :11443).
-            # NOTE: apps-vms NOW carries postBuild.substituteFrom cluster-vars (needed for
-            # ${UNIFI_L4_VIP} in 50-service-l4.yaml), so Flux envsubst DOES run over this userData.
-            # Every shell brace-expansion below is therefore escaped as $${...}, which envsubst emits
-            # as a literal $${...} — verified with `flux envsubst`. Bare $VAR and $(...) are left alone
-            # by envsubst and need no escaping. NEVER write an unescaped $${...} here, and never write
-            # an INDEXED expansion unescaped: envsubst hard-fails on `[` ("missing closing brace")
-            # and would break the whole apps-vms apply. CORRECTION (2026-09-01, measured against
-            # flux 2.4.0 `envsubst --strict`): escaping IS total — $${ARR[0]} emits the literal
-            # text safely. Only the UNESCAPED indexed form is fatal. The earlier "escaped or not"
-            # wording in clusters/base/apps-vms.yaml overstated it.
+            # INLINE, and it MUST stay <= 2048 bytes. That ceiling was MEASURED against the
+            # DEPLOYED KubeVirt v1.9.0 rather than quoted: a server-side dry-run apply of an
+            # otherwise-identical VM accepted 2048 bytes of userData and rejected 2049 with
+            # "cloudInitNoCloud userdata exceeds 2048 byte limit. Should use UserDataSecretRef for
+            # larger data." The payload below is ~1.5 KB; keep additions small.
+            #
+            # WHAT IT DOES: installs qemu-guest-agent (the KubeVirt AgentConnected signal, which is
+            # also the proof cloud-init ran) and preps Podman for UOS, then writes `install-uos`
+            # plus a systemd unit that runs it on EVERY boot. The unit — not cloud-init — is what
+            # makes a later URL change take effect, because cloud-init will not re-run per-instance
+            # modules while the instance-id is unchanged.
+            #
+            # `install-uos` IS IDEMPOTENT AND WILL NOT REINSTALL OVER A WORKING CONTROLLER. It bails
+            # out the moment systemd knows a `uosserver.service` — which the live guest ALREADY has:
+            # the serial console log for the current boot shows both `uosserver.service` and
+            # `uosserver-updater.service` starting, and the root filesystem is 6.3 GB of 40 GB used.
+            # UOS is installed here; see the README for what is actually wrong (the guest lost its
+            # IP). A stamp file at /var/lib/uos-installed is the second, weaker guard for the case
+            # where the unit name changes in some future UOS release.
+            #
+            # ENVSUBST: apps-vms declares postBuild.substituteFrom (for ${UNIFI_L4_VIP} in
+            # 50-service-l4.yaml), so Flux's envsubst DOES run over this text. ${BASE_DOMAIN} below
+            # is a deliberate substitution. Everything else is bare `$name` or `$(cmd)`, both of
+            # which envsubst leaves untouched — verified against the live VMI, whose rendered
+            # userData still carries its shell variables verbatim. There is deliberately NO
+            # brace-form shell expansion left in this payload, so nothing here needs escaping; if
+            # you add one, escape it per the contract in clusters/base/apps-vms.yaml, and NEVER
+            # write an indexed expansion.
            userData: |-
              #cloud-config
              hostname: unifi
              fqdn: unifi.${BASE_DOMAIN}
              package_update: true
              package_upgrade: false
-              packages: [qemu-guest-agent, podman, uidmap, slirp4netns, ca-certificates, curl, jq, cloud-guest-utils]
+              packages: [qemu-guest-agent, podman, uidmap, slirp4netns, ca-certificates, curl]
              write_files:
                - path: /usr/local/sbin/install-uos
                  permissions: '0755'
                  content: |
-                    #!/usr/bin/env bash
+                    #!/bin/bash
                    set -euo pipefail
-                    if [ -z "$${UOS_URL:-}" ]; then
-                      UOS_URL="$(curl -fsSL https://fw-update.ui.com/api/firmware-latest | jq -r '._embedded.firmware|map(select(.product=="unifi-os-server" and .platform=="linux-x64"))|sort_by(.version_major,.version_minor,.version_patch)|last._links.data.href')"
-                    fi
-                    [ -n "$${UOS_URL}" ] && [ "$${UOS_URL}" != "null" ] || { echo "no UOS URL"; exit 1; }
-                    t="$(mktemp)"; echo "downloading $${UOS_URL}"; curl -fL --retry 5 --retry-delay 10 -o "$t" "$UOS_URL"; chmod +x "$t"; echo "installing"; yes | "$t"; echo "done"
+                    d=/run/uos; mkdir -p $d
+                    mountpoint -q $d || mount -o ro LABEL=UOSDATA $d
+                    p=$(tr -d '\r\n' < $d/console-password || true)
+                    case "$p" in ""|REPLACE-ME) ;; *) echo "ubuntu:$p" | chpasswd ;; esac
+                    systemctl cat uosserver.service >/dev/null 2>&1 && exit 0
+                    s=/var/lib/uos-installed
+                    [ -e $s ] && exit 0
+                    u=$(tr -d '\r\n' < $d/installer-url || true)
+                    case "$u" in https://*) ;; *) echo "UOS installer-url not set yet"; exit 0;; esac
+                    t=$(mktemp)
+                    curl -fL --retry 5 --retry-delay 10 -o $t "$u"
+                    chmod +x $t
+                    yes y | $t install || yes y | $t
+                    rm -f $t; date -Is > $s
+                - path: /etc/systemd/system/uos-install.service
+                  content: |
+                    [Unit]
+                    Description=Install UniFi OS Server
+                    Wants=network-online.target
+                    After=network-online.target
+                    [Service]
+                    Type=oneshot
+                    ExecStart=/usr/local/sbin/install-uos
+                    StandardOutput=journal+console
+                    [Install]
+                    WantedBy=multi-user.target
              runcmd:
-                - [ systemctl, enable, --now, qemu-guest-agent ]
-                - [ systemctl, enable, --now, podman.socket ]
-                - [ bash, -lc, "/usr/local/sbin/install-uos 2>&1 | tee /var/log/uos-install.log > /dev/console" ]
+                - [systemctl, enable, --now, qemu-guest-agent]
+                - [systemctl, enable, --now, podman.socket]
+                - [systemctl, enable, --now, uos-install.service]
@@ -21,8 +21,61 @@
 # k3s v1.31 — but the shared-key split is the lower-risk, Cilium-native pattern.)
 #
 # selector kubevirt.io/vm=unifi -> the virt-launcher pod; masquerade forwards the declared ports
-# into the guest. externalTrafficPolicy: Local preserves the LAN client source IP and keeps the
-# VIP pinned to the node running the VM (also what L2 announcement does).
+# into the guest.
+#
+# -------------------------------------------------------------------------------------------
+# externalTrafficPolicy: Cluster — CORRECTED 2026-09-14 after an 8-DAY LAN OUTAGE.
+# -------------------------------------------------------------------------------------------
+# This file used to say `Local`, justified as "preserves the LAN client source IP and keeps the
+# VIP pinned to the node running the VM (also what L2 announcement does)". BOTH HALVES OF THAT
+# WERE FALSE ON THIS CLUSTER, and the second one took the UniFi controller off the LAN entirely.
+#
+# 1) L2 ANNOUNCEMENT DOES NOT FOLLOW THE BACKEND. Cilium's L2 announcer elects one lease holder
+#    per Service among the nodes matching the CiliumL2AnnouncementPolicy `default-l2` — which
+#    matches ALL linux nodes — and it does NOT filter that set by which nodes hold a backend.
+#    MEASURED on prod 2026-09-14: the unifi VM ran on k3s-prod-1 while BOTH
+#    `cilium-l2announce-unifi-unifi-l4-tcp` and `-udp` were held by k3s-prod-2. With `Local`, an
+#    announcing node that holds no backend has nowhere to send the packet and answers ICMP port
+#    unreachable. 192.168.2.21:8443, :8080 and :11443 were dead from the LAN for up to 8 days
+#    (the leases were 8 days old); the operator's controller UI and device inform path were down.
+#    It does NOT self-heal: the lease holder keeps RENEWING after the backend moves, so only
+#    deleting the Lease forces a re-election — and that re-election is random, so it can pick a
+#    backend-less node again. See apps/wave-0/pihole-dns.yaml, which hit this first and is the
+#    reference implementation this file now follows.
+#
+# 2) `Local` WAS NEVER PRESERVING THE CLIENT IP HERE ANYWAY — this is a KubeVirt VM. The
+#    interface in 30-virtualmachine.yaml is `masquerade: {}`, which is KubeVirt's NAT binding: it
+#    SNATs everything from the virt-launcher pod into the guest over a private link, so the UniFi
+#    controller has always seen the pod-side masquerade gateway as the source, never the LAN
+#    client. There is a SECOND translation below the Service, and it already destroyed the very
+#    thing `Local` was being kept for. So the client-IP cost of this change is ZERO for UniFi:
+#    it is giving up an address the guest could not see in the first place.
+#
+#    Nothing UniFi depends on breaks: device identity in the adoption/inform flow is the device
+#    MAC (and the device reports its own IP inside the inform payload), not the packet source,
+#    and guest-portal authorization runs on the gateway appliance, not on this controller.
+#
+# `Cluster` makes EVERY node able to serve the VIP by forwarding to wherever the VM runs, which
+# is what makes this survive a reschedule and a rebuild.
+#
+# NO CHANGE IS NEEDED IN 40-networkpolicy.yaml, AND THAT WAS VERIFIED RATHER THAN ASSUMED.
+# Under `Cluster` the forwarded second hop is sourced from the ingress node and carries Cilium's
+# reserved `remote-node` identity. pihole-dns.yaml has to name `remote-node` explicitly in its
+# CiliumNetworkPolicy — but that is because its policy deliberately omits `cluster`.
+# unifi-allow-l4-ingress admits `cluster`, and Cilium's `cluster` entity SUBSUMES `remote-node`
+# (along with host/init/unmanaged). Confirmed on prod 2026-09-14 by dumping the endpoint's
+# datapath policy map (`cilium-dbg bpf policy get`) while the CNP was in its unmodified state:
+# `reserved:remote-node` was already an Allow on the L4 ports. Adding `remote-node` to that rule
+# would be a no-op, so it is deliberately NOT added here — do not "fix" it.
+#
+# NO loadBalancerSourceRanges HERE, DELIBERATELY — and this is where this file departs from
+# pihole-dns.yaml. PiHole added `loadBalancerSourceRanges: [${LAN_CIDR}]` because it was giving
+# up a restriction it actually had and genuinely needed to be LAN-only. These Services never had
+# a source restriction at all (unifi-allow-l4-ingress admits `world`), so `Cluster` removes no
+# protection and there is nothing to compensate for. Adding a LAN-only filter during an outage
+# fix would be a NEW restriction that could silently break a remote site's device informing over
+# WAN — trading this outage for a subtler one. If UniFi should be LAN-only, that is its own
+# change, made deliberately and tested against the device fleet.
 #
 # VIP: ${UNIFI_L4_VIP} (cluster-vars, R-ENV-02; dev 192.168.1.54, confirmed free, inside
 # default-pool and reserved in tofu — the Gateway already holds the pool's first IP, dev .53).
@@ -49,7 +102,7 @@ metadata:
    external-dns.alpha.kubernetes.io/hostname: "unifi.${BASE_DOMAIN}"
 spec:
  type: LoadBalancer
-  externalTrafficPolicy: Local
+  externalTrafficPolicy: Cluster
  selector:
    kubevirt.io/vm: unifi
  ports:
@@ -72,7 +125,7 @@ metadata:
    lbipam.cilium.io/ips: "${UNIFI_L4_VIP}"
 spec:
  type: LoadBalancer
-  externalTrafficPolicy: Local
+  externalTrafficPolicy: Cluster
  selector:
    kubevirt.io/vm: unifi
  ports:
@@ -1,18 +1,48 @@
 # UniFi Network controller (UniFi OS Server) — VM onboarding

-> **LIVE — partially.** Reconciled by the **non-gating `apps-vms`** Flux Kustomization
-> (`clusters/base/apps-vms.yaml`, `dependsOn: platform-config`, `wait: false`). VMs are a separate
-> lifecycle from the rendered app waves, and UniFi has no in-cluster dependents, so a slow import
-> or install cannot stall the app tier.
+> **LIVE — but the controller is unreachable, and NOT for the reason this file used to claim.**
+> Reconciled by the **non-gating `apps-vms`** Flux Kustomization (`clusters/base/apps-vms.yaml`,
+> `dependsOn: platform-config` + `platform-config-cdi`, `wait: false`). VMs are a separate lifecycle
+> from the rendered app waves, and UniFi has no in-cluster dependents, so a slow import or install
+> cannot stall the app tier.
 >
-> **Status (verified 2026-08-26):**
-> - `longhorn-vm` StorageClass — **live** (RWX / Block / migratable).
-> - CDI import — **Succeeded** (100%); `unifi-rootdisk` PVC Bound, 40Gi, RWX, `longhorn-vm`.
-> - VM — **Running**, guest agent connected, Ubuntu 24.04.4 LTS, live-migratable, on `k3s-dev-1`.
-> - L4 LoadBalancer VIP `192.168.1.54` — **allocated** on both Services.
-> - **UniFi OS Server itself is NOT installed.** Port `11443` does not answer from in-cluster
->   (the CNP explicitly permits `cluster` → `:11443`, so this is "nothing listening", not policy).
->   The guest is a bare, prepped Ubuntu. **This is the one remaining step** — see Open question 1.
+> **Status (re-verified against live prod 2026-09-14):**
+> - `longhorn-vm` StorageClass — **live**; `unifi-rootdisk` PVC Bound, **40Gi, RWX, Block**.
+> - CDI import — **Succeeded** (100%).
+> - VM — **Running** on **`k3s-prod-1`**, guest agent connected, Ubuntu 24.04.4 LTS,
+>   `LiveMigratable=True` / `StorageLiveMigratable=True`. VMI age 34h, VM 8d.
+> - L4 LoadBalancer VIP **`192.168.2.21`** — allocated and held on both Services.
+> - **UniFi OS Server IS INSTALLED.** This reverses the previous entry here. See below.
+> - **The guest has no IP address.** That — not a missing install — is why `:11443`, `:8443` and
+>   `:8080` refuse connections.
+
+## What is actually wrong (2026-09-14)
+
+The earlier note in this file said "UOS is NOT installed; the guest is a bare, prepped Ubuntu".
+That was wrong, and acting on it would have meant reinstalling over a working controller.
+
+Evidence, all read-only, from the live cluster:
+
+| Claim | How it was checked | Result |
+|---|---|---|
+| UOS is installed | `kubectl -n unifi logs virt-launcher-unifi-… -c guest-console-log` | the current boot starts **`uosserver.service` — UniFi OS Server Service** and **`uosserver-updater.service`** |
+| …and it is a real install, not a stub | KubeVirt guest-agent `filesystemlist` subresource | `/` is **6.3 GB used of 40 GB** — a bare Ubuntu cloud image with our packages is ~2 GB |
+| the guest has no IP | `kubectl -n unifi get vmi unifi -o json` → `.status.interfaces` | `enp1s0`, `linkState: up`, **no `ipAddress` field at all**; the `kubectl get vmi` IP column is empty |
+| …confirmed at the link layer | `kubectl -n unifi exec virt-launcher-… -c compute -- ip neigh` | **`10.0.2.2 dev k6t-eth0 FAILED`** — the guest does not answer ARP for its masquerade address |
+| the ports are dead end-to-end | `/dev/tcp` probes from inside virt-launcher, to the pod IP **and** to `10.0.2.2` directly | 11443 / 8443 / 8080 / **22** all refused — i.e. the VIP and the CNP are exonerated |
+
+So the controller is installed and its units start; nothing downstream of the guest's own network
+stack can work. The interface was fine at boot (the console log reaches `network-online.target` at
+~10s and cloud-init completes at 18.5s), so the address was lost afterwards — the obvious suspect is
+UOS taking over host networking, but **that has not been proven and cannot be, from outside the
+guest.** Diagnosing it needs a shell, which is the second problem below.
+
+**There is currently no way into this guest.** The shipped cloud-init installs no SSH key and sets
+no password, so the stock `ubuntu` account is locked and a serial console reaches a login prompt
+nobody can answer. SSH would not rescue it either: the masquerade interface forwards **only** the
+ports declared in `30-virtualmachine.yaml`, and 22 is not one of them — the probe above shows the
+guest RSTs on 22 exactly as it does on 11443. Closing that hole is what `console-password` in the
+new Secret is for.

 ## What this is

@@ -29,24 +59,39 @@ datastore** inside a Podman container stack — so **no separate MongoDB compani
 | `namespace.yaml` | `unifi` namespace: app-namespace label (Kyverno + default-deny apply), `gateway-access=shared`, backup annotation |
 | `10-default-deny.yaml` | R-NET-01 baseline: deny all, allow only DNS |
 | `20-datavolume.yaml` | CDI **http** import of the Ubuntu 24.04 cloud image onto a `longhorn-vm` **RWX/Block** disk (**40Gi**). First real CDI http import on the cluster |
-| `30-virtualmachine.yaml` | The VM: 2 vCPU / 4Gi, `running: true`, `evictionStrategy: LiveMigrate`, minimal **inline** cloud-init (SSH key, qemu-guest-agent, Podman prep) |
+| `30-virtualmachine.yaml` | The VM: 2 vCPU / 4Gi, `running: true`, `evictionStrategy: LiveMigrate`, a **pinned firmware UUID** (= the cloud-init instance-id), the **UOSDATA secret disk**, and a minimal **inline** cloud-init that installs `install-uos` + a per-boot systemd unit |
 | `40-networkpolicy.yaml` | Additive CNP allows: L4 ingress ports, controller world+DNS egress, and CDI-importer egress |
-| `50-service-l4.yaml` | Two `type=LoadBalancer` Services (TCP+UDP) sharing **one pinned Cilium VIP** `192.168.1.54`; external-dns A record |
+| `50-service-l4.yaml` | Two `type=LoadBalancer` Services (TCP+UDP) sharing **one pinned Cilium VIP** `${UNIFI_L4_VIP}` (prod **192.168.2.21**); external-dns A record |
+| `unifi-uos-installer.sops.yaml` | **SOPS-encrypted.** The operator's UOS installer URL + guest console password, mounted into the guest as a disk |
+| `unifi-uos-installer.sops.yaml.example` | Plaintext template + the operator hand-off steps (never applied, never encrypted) |
 | `kustomization.yaml` | The reconciled resource list (referenced by `apps/vms/kustomization.yaml`) |

-The optional L7 HTTPRoute (`90-httproute-optional.yaml`) was **dropped**, not merely disabled: UOS
-serves HTTPS on `:11443`, so a Gateway route needs a `BackendTLSPolicy` that is not confirmed on
-this Cilium version. Browser access is via the L4 VIP. Re-add it if/when that lands.
+The optional L7 HTTPRoute was **dropped, and the file does not exist**: UOS serves HTTPS on
+`:11443`, so a Gateway route needs a `BackendTLSPolicy` that is not confirmed on this Cilium
+version. Browser access is via the L4 VIP. Re-add it if/when that lands.

-### Cloud-init delivery — two constraints learned the hard way
+### Cloud-init delivery — three constraints, all measured on the deployed KubeVirt (v1.9.0)

-1. **KubeVirt caps inline `userData` at 2048 bytes.** The original rich cloud-init (full Podman
-   prep + `install-uos` helper) blew past it. A `userDataSecretRef` was tried, then reverted; the
-   shipped config is a **minimal ~1.1 KB inline `userData`**. Keep additions small or move to a
-   Secret deliberately.
-2. **`apps-vms` must NOT use `postBuild.substituteFrom`.** Flux variable substitution rewrote
-   `$`-bearing text inside the cloud-init payload and **corrupted it**. `clusters/base/apps-vms.yaml`
-   therefore carries no `substituteFrom` — unlike every app wave. Do not "restore" it for consistency.
+1. **Inline `userData` is capped at 2048 bytes.** MEASURED, not quoted: a server-side dry-run apply
+   of an otherwise-identical VM accepted 2048 bytes and rejected 2049 with *"cloudInitNoCloud
+   userdata exceeds 2048 byte limit. Should use UserDataSecretRef for larger data."* The shipped
+   payload is ~1.45 KB. The API field for the escape hatch is spelled **`secretRef`** (the Go name
+   is `UserDataSecretRef`); `userDataSecretRef` is not a YAML key and trying it will silently
+   validate as an unknown field.
+2. **The firmware UUID is the cloud-init instance-id, and editing `userData` alone changes
+   nothing.** The NoCloud seed's `instance-id` is exactly
+   `spec.template.spec.domain.firmware.uuid`, which KubeVirt's webhook stamps onto the **VM object**
+   (so it survives restarts), and cloud-init's NoCloud datasource compares it to the guest's DMI
+   product UUID. Same id → cached datasource restored, new payload never read, `write_files` and
+   `runcmd` skipped. This is why the previously shipped "unattended install" could never have taken
+   effect on a second boot. The UUID is now **pinned in git**, with bumping it as the documented way
+   to force a re-run. See the long comment in `30-virtualmachine.yaml`.
+3. **`apps-vms` DOES use `postBuild.substituteFrom`.** This file used to say it must not — that has
+   been false since 2026-08-31, when `${UNIFI_L4_VIP}` landed in `50-service-l4.yaml`. Flux's
+   envsubst therefore runs over the cloud-init payload, and the escape contract in
+   `clusters/base/apps-vms.yaml` is in force. Bare `$name` and `$(cmd)` are left alone (verified
+   against the live VMI's rendered userData); brace-form shell expansion must be escaped; an
+   indexed expansion is a hard error that fails the whole Kustomization.

 ### Node prerequisites this VM forced onto the cluster

@@ -56,15 +101,31 @@ this Cilium version. Browser access is via the L4 VIP. Re-add it if/when that la
 - **`longhorn-scratch`** — a single-replica StorageClass for CDI scratch space; the default
  3-replica class made the import fail with insufficient storage.

-## UOS install method (researched)
+## UOS install method (researched 2026-09-14)

- **Host:** Ubuntu 24.04 LTS x86-64, systemd, **Podman 4.9.3+**, `slirp4netns` 1.2+, `uidmap`. Min
-  2 GB RAM / 10 GB disk (we give 4 GB / 60 GB). Podman must be at `/usr/bin/podman`.
- **Install:** download the signed installer from `fw-download.ubnt.com` (URL obtained from
-  `ui.com/download/software/unifi-os-server`), `chmod +x`, run **as root**. UI then on
-  **`https://<host>:11443`**.
- **Confidence:** *High* on requirements, ports, and the download→chmod→run shape (multiple
-  independent 2025–2026 sources agree). *Lower* on **fully unattended** install — see risks.
+- **Host:** Ubuntu 24.04 LTS x86-64, systemd, **Podman 4.9.3+**, `slirp4netns` 1.2+, `uidmap`.
+  Vendor/community minimum is 2 vCPU / 4 GB RAM / ~25 GB disk; we give **2 vCPU / 4 GiB / 40Gi**
+  (the 40Gi figure is the DataVolume and the Bound PVC — an earlier "60 GB" claim here was wrong).
+  Podman must be at `/usr/bin/podman`.
+- **Install:** obtain the download link from `ui.com/download/software/unifi-os-server` while signed
+  in to a (free) Ubiquiti account, `chmod +x`, run **as root**. UI then on **`https://<host>:11443`**.
+- **Is the URL a short-lived signed link?** *Probably not.* The links look like
+  `https://fw-download.ubnt.com/data/unifi-os-server/<hash>-linux-x64-<version>-<uuid>.<n>-x64` with
+  **no signature query string**, and public community installers hard-code them. It is
+  account-derived and per-release, not time-limited. It is kept in SOPS anyway — cheap, and it keeps
+  account-derived material out of plaintext config — but do **not** build logic around expiry.
+- **Can it run unattended? Yes in practice, no officially — and this is the honest answer.**
+  Ubiquiti documents no `--silent` flag, no answer file and no environment variables. What the
+  ecosystem actually does is pipe confirmations in: the widely used community installer
+  (`dgodibadze/UniFi_OS_Server`) runs `yes y | "$file" install`, and vendor-adjacent walkthroughs run
+  either `./<binary> install` or a bare `sudo ./<binary>`. `install-uos` therefore does
+  `yes y | $t install || yes y | $t` — the documented-by-practice form first, the bare form as a
+  fallback for builds that take no subcommand. **This has not been executed end-to-end on our guest**
+  (no URL has been supplied, and UOS is already installed here), so treat it as "established by
+  convergent third-party practice", not as verified-by-us.
+- The previously shipped helper had two defects worth recording: it resolved the URL from
+  `fw-update.ui.com/api/firmware-latest`, an endpoint nothing in this repo ever verified lists
+  `unifi-os-server`, and it invoked the binary with **no `install` subcommand**.

 ### Ports (device adoption needs the L4 ones — the L7 Gateway cannot express them)

@@ -78,76 +139,143 @@ this Cilium version. Browser access is via the L4 VIP. Re-add it if/when that la
 | 3478 | UDP | **STUN** (device ⇄ controller) |
 | 10001 | UDP | **L2 device discovery** |

+**22/TCP is deliberately absent**, and that is load-bearing: a masquerade interface forwards only
+the ports it declares, so SSH into this guest is impossible by construction. Use the serial console.
+
 ## L4 exposure design (the hard part)

 The shared Gateway is L7 HTTPS only (`:443` host-routed). It **cannot** carry raw TCP `8080`/`6789`
 or any UDP (`3478`/`10001`) — exactly the ports adoption rides. So:

 - **One VIP, two Services.** `unifi-l4-tcp` + `unifi-l4-udp` share a single LoadBalancer IP via
-  Cilium `lbipam.cilium.io/sharing-key: unifi`, pinned to **`192.168.1.54`** (`lbipam.cilium.io/ips`).
-  The VIP is pulled from the existing `default-pool` (192.168.1.53–.60) and **ARP-announced on the
-  flat LAN by the existing `default-l2` CiliumL2AnnouncementPolicy** — no new Cilium config.
+  Cilium `lbipam.cilium.io/sharing-key: unifi`, pinned through `${UNIFI_L4_VIP}`
+  (`lbipam.cilium.io/ips`) — **192.168.2.21 on prod**. The VIP comes from the existing
+  `default-pool`, whose live prod block is **192.168.2.20–192.168.2.30** with **192.168.2.20 held by
+  the shared Gateway** (`cilium-gateway-shared`), and is ARP-announced on the flat LAN by the
+  existing `default-l2` CiliumL2AnnouncementPolicy — no new Cilium config. (The `192.168.1.53–.60`
+  / `.53` figures this section used to quote were **dev** addressing and are gone; dev has been
+  decommissioned. Neighbours in the prod pool today: `.22` crafty, `.23` pihole-dns.)
 - `selector: kubevirt.io/vm=unifi` → the virt-launcher pod; the VM's `masquerade` iface forwards the
-  declared ports into the guest. `externalTrafficPolicy: Local` preserves LAN client source IP.
- **Device-adoption story:** point devices' **inform host** at the VIP (`http://192.168.1.54:8080/inform`)
-  — via the controller's *Override inform host* setting, `set-inform` on the device, or DHCP option 43.
-  Because the VIP is L2-announced on the devices' own subnet (192.168.1.0/24), unicast inform + STUN
-  reach it. **Limitation:** broadcast-based L2 auto-discovery (10001/udp) does **not** cross the pod
-  masquerade boundary, so zero-touch "device just appears" adoption is unreliable — expect to use
-  explicit inform. Devices on other VLANs must route to the VIP and be inform-pointed anyway.
- **Reusable pattern (== the deferred `minecraft` :25565 problem):** L4-only workload → Cilium
-  LoadBalancer on a pinned, L2-announced VIP with a per-app sharing key, A record via external-dns.
-  `minecraft` is the single-TCP-port special case of this multi-port TCP+UDP design.
+  declared ports into the guest.
+- **`externalTrafficPolicy: Cluster`, corrected 2026-09-14 after an 8-day LAN outage.** This file
+  used to advertise `Local` "to preserve the LAN client source IP". Both halves were false here:
+  Cilium's L2 announcer elects a lease holder without regard to which node holds a backend (the
+  leases sat on `k3s-prod-2` while the VM ran on `k3s-prod-1`, so `Local` had nowhere to forward),
+  and KubeVirt's `masquerade` binding had already NATed the client IP away before the guest ever saw
+  it. The full reasoning — including why `40-networkpolicy.yaml` needs no `remote-node` entry and
+  why no `loadBalancerSourceRanges` was added — is in `50-service-l4.yaml`.
+- **Device-adoption story:** point devices' **inform host** at the VIP
+  (`http://192.168.2.21:8080/inform`) — via the controller's *Override inform host* setting,
+  `set-inform` on the device, or DHCP option 43. Because the VIP is L2-announced on the devices' own
+  subnet (**192.168.2.0/24**, `LAN_CIDR`), unicast inform + STUN reach it. **Limitation:**
+  broadcast-based L2 auto-discovery (10001/udp) does **not** cross the pod masquerade boundary, so
+  zero-touch "device just appears" adoption is unreliable — expect to use explicit inform. Devices
+  on other VLANs must route to the VIP and be inform-pointed anyway.
+- **Reusable pattern:** L4-only workload → Cilium LoadBalancer on a pinned, L2-announced VIP with a
+  per-app sharing key, A record via external-dns. `crafty` (`.22`) is the same shape and is live.

-**UI access:** `https://unifi.home.keithjackson.dev:11443` (A record → VIP). The port-less
-`https://unifi.home.keithjackson.dev` via the Gateway is optional and needs a BackendTLSPolicy
-(UOS is HTTPS-only on 11443) — see `90-httproute-optional.yaml`.
+**UI access:** `https://unifi.home.keithjackson.dev:11443`. That name resolves to the VIP and not to
+the Gateway on purpose: both `platform/coredns/coredns-custom.yaml` (in-cluster) and
+`apps/wave-0/pihole.yaml` (LAN split-horizon) carve `unifi.${BASE_DOMAIN}` out of the
+zone-wide `${GATEWAY_VIP}` answer and point it at `${UNIFI_L4_VIP}`. `${BASE_DOMAIN}` on prod is the
+apex `home.keithjackson.dev` (confirmed live in the `cluster-vars` ConfigMap) after the 2026-09-13
+flip, so this hostname is current, not a dev leftover.
+
+## The operator's one field — installing UOS without a shell
+
+`unifi-uos-installer.sops.yaml` is a SOPS-encrypted Secret with two keys. KubeVirt mounts it into
+the guest as a read-only iso9660 disk labelled `UOSDATA` (one file per key), and an in-guest
+`uos-install.service` reads it **on every boot**:
+
+```bash
+sops apps/vms/unifi/unifi-uos-installer.sops.yaml    # fill installer-url and/or console-password
+git commit && git push                               # merge to the branch prod's Flux tracks
+kubectl -n unifi delete vmi unifi                    # `running: true` recreates it; no virtctl needed
+kubectl -n unifi logs -f $(kubectl -n unifi get pod -l kubevirt.io=virt-launcher -o name | head -1) \
+  -c guest-console-log                               # watch the boot + the install, read-only
+```
+
+Design notes that matter if you change this:
+
+- **The Secret is a disk, not `cloudInitNoCloud.secretRef`.** `secretRef` would lift the 2048-byte
+  cap but would move the whole cloud-config into ciphertext: unreviewable in diffs, invisible to the
+  L0 dollar-collapse guard, and still subject to Flux's envsubst (which runs over **decrypted**
+  resources) — the exact shape of the 2026-09-13 `nextcloud-db` incident. Script in plaintext,
+  operator values in SOPS.
+- **A URL change needs no UUID bump.** The disk is rebuilt from the Secret on every VMI start and
+  the systemd unit re-reads it every boot. Only a change to the cloud-init payload itself needs the
+  firmware-UUID bump.
+- **`install-uos` will not reinstall over a working controller.** It exits as soon as systemd knows
+  a `uosserver.service`, with `/var/lib/uos-installed` as a weaker second guard. Given the live
+  guest already has UOS, this guard is the difference between "safe to merge" and "destroys the
+  controller on next boot".
+- **`apps-vms` had no SOPS `decryption` stanza** — this is the first encrypted content under
+  `apps/vms/`, so the stanza was added to both `clusters/dev/kustomization.yaml` and
+  `clusters/prod/kustomization.yaml`. Without it kustomize hands Flux the raw SOPS document and the
+  guest mounts a disk full of ciphertext, with the cluster reporting everything healthy.

 ## Open questions / risks

-1. **Unattended install (HIGH) — STILL OPEN. This is the blocker.** The installer is a **signed,
-   account-tied** URL that **rotates/expires** (cannot be committed) and is documented as
-   **interactive** (no official silent flag). The shipped cloud-init had to be cut to ~1.1 KB for
-   the inline `userData` limit, so the `install-uos` helper is **no longer baked into the guest**.
-   **Decision needed:** operator runs the install by hand at bring-up (current de-facto answer), or
-   invest in a verified silent path (Secret-delivered cloud-init + a fetched-at-boot URL).
-2. **CDI http import (MEDIUM) — RESOLVED in practice.** The import succeeded (first http/qcow2 CDI
+1. **The guest lost its IP (HIGH) — THE LIVE BLOCKER, and it needs the operator.** Diagnosis
+   requires a shell, which requires `console-password` above plus one restart. First things to run
+   on the console: `ip -4 a`, `networkctl status enp1s0`, `journalctl -u systemd-networkd`,
+   `ls /etc/netplan`, and `systemctl status uosserver`. A plain restart may well restore DHCP on its
+   own (the address survived the first ~34h of this boot's life), but that would hide the cause, so
+   capture the state before rebooting a second time if you can.
+2. **Unattended install (MEDIUM) — mechanism shipped, end-to-end run NOT witnessed.** See the
+   install-method section: no official silent flag exists, `yes y | <installer> install` is the
+   convergent community practice, and it has not been executed on our guest. Treat the first real
+   install as something to watch on the console log, not as a fire-and-forget.
+3. **CDI http import (LOW) — RESOLVED in practice.** The import succeeded (first http/qcow2 CDI
   import on this cluster). Still no checksum on an http source, and the URL tracks a *moving*
   Ubuntu 24.04 build — pin a dated build dir if reproducibility matters. Needed two cluster-level
   fixes (`nonroot-devices`, `longhorn-scratch`) — see above.
-3. **Boot firmware (LOW) — RESOLVED.** Boots as shipped; running Ubuntu 24.04.4 LTS.
-4. **VIP `192.168.1.54` (LOW) — RESOLVED.** Allocated and held by both Services, inside the
-   `192.168.1.53–.60` pool (`.53` is the shared Gateway).
-5. **Longhorn RWX prerequisite (was BLOCKING) — RESOLVED.** `longhorn-vm` is live (RWX / Block /
+4. **Boot firmware (LOW) — RESOLVED.** Boots as shipped; running Ubuntu 24.04.4 LTS.
+5. **VIP `192.168.2.21` (LOW) — RESOLVED.** Allocated and held by both Services, inside the live
+   prod pool `192.168.2.20–.30`, not colliding with the Gateway (`.20`), crafty (`.22`), pihole-dns
+   (`.23`) or the node addresses (`.10/.11/.12`).
+6. **Longhorn RWX prerequisite (was BLOCKING) — RESOLVED.** `longhorn-vm` is live (RWX / Block /
   migratable); the VMI reports `LiveMigratable=True` and `StorageLiveMigratable=True`.
-6. **Licensing (LOW).** UOS self-host is free; a Ubiquiti account is needed only to fetch the
+7. **Licensing (LOW).** UOS self-host is free; a Ubiquiti account is needed only to fetch the
   installer and for optional remote access.
-7. **Broadcast adoption (LOW, by design).** L2 auto-discovery (`10001/udp`) does not cross the pod
+8. **Broadcast adoption (LOW, by design).** L2 auto-discovery (`10001/udp`) does not cross the pod
   masquerade boundary — see the L4 section. Expect explicit inform-host adoption.
+9. **No `virtctl` in the devcontainer (LOW).** Restart and read-only console both work with plain
+   `kubectl` (above). An *interactive* console — the thing `console-password` unlocks — needs
+   `virtctl` on the operator's path; it is a single static binary from the KubeVirt release matching
+   the cluster's **v1.9.0**.

 ## Remaining bring-up

-Steps 1–4 below are **done**. The sequence is kept because it is also the recovery/rebuild runbook.
+Steps 1–5 are **done**. The sequence is kept because it is also the recovery/rebuild runbook, so it
+is written for a from-scratch cluster; the prod addresses are the live ones.

-1. ~~`longhorn-vm` StorageClass live; `192.168.1.54` free.~~ **Done.**
+1. ~~`longhorn-vm` StorageClass live; a free address in the LB pool.~~ **Done** (`192.168.2.21`).
 2. ~~Wire into a reconciled path~~ — **done**, via `apps/vms/` + the non-gating `apps-vms`
-   Kustomization (not an app wave).
+   Kustomization (not an app wave), including its SOPS `decryption` stanza in both overlays.
 3. ~~CDI import~~ — **done**: `kubectl -n unifi get dv unifi-rootdisk` → `Succeeded`.
 4. ~~VM + VIP~~ — **done**: `kubectl -n unifi get vmi unifi` → `Running`; both Services show
-   `192.168.1.54`.
-5. **→ NEXT: install UOS in the guest.** SSH in (the inline cloud-init installs the operator's key
-   and `qemu-guest-agent`) or `virtctl console unifi`, fetch the signed installer URL from
-   ui.com/download/software/unifi-os-server, then `chmod +x` and run it **as root**.
-6. Verify the UI: `https://unifi.home.keithjackson.dev:11443` (or `https://192.168.1.54:11443`),
+   `192.168.2.21`.
+5. ~~Install UOS in the guest~~ — **done** (it was already done when this file claimed otherwise;
+   `uosserver.service` starts on every boot). On a REBUILD this is where the Secret does the work:
+   fill `installer-url`, commit, and the guest installs itself on first boot.
+6. **→ NEXT, and it is the operator's:** fill `console-password`, restart the VM once, get on the
+   console and find out why `enp1s0` has no address. Until that is fixed nothing below can pass.
+7. Verify the UI: `https://unifi.home.keithjackson.dev:11443` (or `https://192.168.2.21:11443`),
   complete the first-run wizard.
-7. Verify DNS: `dig unifi.home.keithjackson.dev` → `192.168.1.54` on the cluster LAN.
-8. Adopt a device: set its inform to `http://192.168.1.54:8080/inform`; confirm it appears + STUN
+8. Verify DNS: `dig unifi.home.keithjackson.dev` → `192.168.2.21` from a LAN client (pihole
+   split-horizon) and from in-cluster (coredns-custom).
+9. Adopt a device: set its inform to `http://192.168.2.21:8080/inform`; confirm it appears + STUN
   connects (green). Test guest portal / throughput if used.
-9. Verify default-deny holds: only the declared L4 ports reachable; VM egress limited to world+DNS.
-10. (Optional) Re-add the L7 HTTPRoute once `BackendTLSPolicy` is confirmed on this Cilium version.
+10. Verify default-deny holds: only the declared L4 ports reachable; VM egress limited to world+DNS.
+11. (Optional) Re-add the L7 HTTPRoute once `BackendTLSPolicy` is confirmed on this Cilium version.

 **Quick health check today:**
 ```bash
 kubectl -n unifi get dv,vmi,svc
 kubectl -n unifi get vmi unifi -o jsonpath='{.status.guestOSInfo.prettyName}{"\n"}'
+# the two that would have caught the current failure:
+kubectl -n unifi get vmi unifi -o jsonpath='{.status.interfaces}{"\n"}'   # expect an ipAddress
+kubectl -n unifi exec "$(kubectl -n unifi get pod -l kubevirt.io=virt-launcher -o name | head -1)" \
+  -c compute -- ip neigh                                                 # expect 10.0.2.2 REACHABLE
 ```
@@ -11,3 +11,11 @@ resources:
  - 30-virtualmachine.yaml
  - 40-networkpolicy.yaml
  - 50-service-l4.yaml
+  # SOPS-encrypted. Carries the operator's UOS installer URL (+ optional SSH key) and is mounted
+  # into the guest as the UOSDATA disk by 30-virtualmachine.yaml. Decrypted by the `apps-vms` Flux
+  # Kustomization, which clusters/dev and clusters/prod patch with the `decryption` stanza — the
+  # FIRST encrypted content under apps/vms, so that patch was added with this file. The plaintext
+  # template + the operator hand-off steps live in the `.example` sibling of the file below, which
+  # is deliberately NOT named here: the L0 no-plaintext-secrets check fails any kustomization whose
+  # text contains an example template's filename, on the assumption it is being applied.
+  - unifi-uos-installer.sops.yaml
@@ -0,0 +1,29 @@
+apiVersion: v1
+kind: Secret
+metadata:
+    name: unifi-uos-installer
+    namespace: unifi
+type: Opaque
+stringData:
+    installer-url: ENC[AES256_GCM,data:pZo/fRSnUmZj2w==,iv:tBWMAL0NwCURCmfzx3UAtryCovcR+Rmh4DdtUiCi4Ig=,tag:ZfLicc3pBWujPHKqfSNOag==,type:str]
+    console-password: ENC[AES256_GCM,data:rQ6v6VjG4uoEShHic+zM,iv:nV7mTJFRsLvd67uZT+KyMrOhUVkERVv53LqsvcE5Qfs=,tag:9J/t2je48DRTVmppPqDfFQ==,type:str]
+sops:
+    kms: []
+    gcp_kms: []
+    azure_kv: []
+    hc_vault: []
+    age:
+        - recipient: age175l8mdpdfu7hq0aml3exs3gykarwjmuvr23sq56s3wjejnyk44wsp4mfzg
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB5M1RwWGhRKzNVenpzS25w
+            WW4vNHFURy9hMjRGeW0wdUJSaHN4MDFhSHlBCm1udi9NOWJ3RGdvOVNnRG9ZUlp4
+            TnVXRi90eFNSMjNVYVpUSmtFTURtU2MKLS0tIExPN2NRZW9CQXBKdUtCUkZSTXVO
+            cE9IcTM2RG9oMmt2Y0xsRExzUjYwUlEK6vq56tnnYvruNcCgijRUsfi3IreXt7fk
+            kgDevz3fOKkEJ3Y8+Mx3RBf3j6Za7L1lW7ft9TyTkBelRpj9bRD1Pg==
+            -----END AGE ENCRYPTED FILE-----
+    lastmodified: "2026-09-19T02:47:13Z"
+    mac: ENC[AES256_GCM,data:DVJZQlHHb0U/F8oQ2iwPSTCvzHNynGZFW4MSHzW+LmNt8ozA7n2/U9prhRdrq3a1MHlaoGAkOFMGoQdZRR83CtZyP6oFoLiAMsRvNjNMgkaT1E3D7dzhjxAiTb+vQk9O467bH3ofm1+I/Ak3VFrNdjTtWFkWltW7MHB8njgPRPM=,iv:Sve3Z6RHKSWcdcEZtphBBmhRxjhfJHu9Dus2vb6K4+0=,tag:OrsGBPJVF1jtOAXCWNXG2Q==,type:str]
+    pgp: []
+    encrypted_regex: ^(data|stringData)$
+    version: 3.9.4
@@ -0,0 +1,71 @@
+# =============================================================================
+# TEMPLATE — NOT APPLIED, NOT ENCRYPTED (.yaml.example is ignored by kustomize and never
+# auto-encrypted by SOPS). Reference scaffold + OPERATOR HAND-OFF.
+#
+# WHAT THIS IS: the two values that (a) let the UniFi VM install UniFi OS Server by itself, with
+# nobody typing commands inside the guest, and (b) give the operator a way INTO that guest at all.
+# KubeVirt mounts this Secret into the VM as a tiny read-only iso9660 disk labelled `UOSDATA` (see
+# the `uosdata` volume in 30-virtualmachine.yaml); each key below becomes a file of the same name on
+# that disk, and the in-guest `uos-install.service` reads them on EVERY boot.
+#
+# READ THIS FIRST — UOS IS ALREADY INSTALLED ON THE LIVE PROD GUEST (verified 2026-09-14, see the
+# README "What is actually wrong"). `installer-url` is therefore NOT the fix for today's outage; it
+# is the rebuild path and the "the install never happened" path. `install-uos` refuses to run the
+# installer at all while systemd knows a `uosserver.service`, so filling this in cannot clobber a
+# working controller. `console-password` IS useful today: it is the only way to get a shell.
+#
+# WHY THE URL IS BEHIND SOPS: it is obtained through the operator's own (free) Ubiquiti account
+# session at ui.com/download/software/unifi-os-server, it identifies a specific build, and it is not
+# ours to redistribute. Treat it as account-derived material, not as public configuration.
+# HONEST CAVEAT, checked 2026-09-14: the resulting `https://fw-download.ubnt.com/data/
+# unifi-os-server/<hash>-linux-x64-<version>-<uuid>.<n>-x64` URL carries NO signature query string,
+# and public community install scripts hard-code these URLs — so it does not behave like a
+# short-lived signed link. It does change every release. Encrypting it costs nothing and keeps the
+# repo's "account-derived material is not config" line clean, but do NOT design around "it expires".
+#
+# HAND-OFF STEPS (operator) — this is the whole job:
+#  (a) Sign in at https://ui.com/download/software/unifi-os-server, pick the Linux (x64) build, and
+#      copy the download link (right-click -> Copy link address). Do NOT download it here; the guest
+#      fetches it itself.
+#  (b) Open the encrypted sibling in your editor:
+#         sops apps/vms/unifi/unifi-uos-installer.sops.yaml
+#  (c) Replace the two REPLACE-ME values. Either may be left as the placeholder — the guest skips a
+#      placeholder rather than failing.
+#  (d) Save/quit (sops re-encrypts in place), commit, push, merge to the branch prod tracks.
+#  (e) Restart the VM once so the new cloud-init instance and the new disk are picked up:
+#         kubectl -n unifi delete vmi unifi        # `running: true` recreates it; no virtctl needed
+#      Watch it come up WITHOUT virtctl:
+#         kubectl -n unifi logs -f $(kubectl -n unifi get pod -l kubevirt.io=virt-launcher \
+#           -o name | head -1) -c guest-console-log
+#  (f) UI: https://192.168.2.21:11443 (prod) or https://unifi.home.keithjackson.dev:11443.
+#
+# IF YOU LATER NEED A NEW URL (new release, dead link): repeat (b)-(e). No firmware-UUID bump is
+# needed for that — the disk is rebuilt from this Secret on every VMI start and the systemd unit
+# re-reads it every boot. The UUID bump in 30-virtualmachine.yaml is only needed when the cloud-init
+# payload ITSELF changes.
+#
+# The file is already listed under `resources:` in apps/vms/unifi/kustomization.yaml, and `apps-vms`
+# is patched with the SOPS `decryption` stanza in clusters/dev + clusters/prod.
+# =============================================================================
+apiVersion: v1
+kind: Secret
+metadata:
+  name: unifi-uos-installer
+  namespace: unifi
+type: Opaque
+stringData:
+  # KEY NAMES ARE LOAD-BEARING: each key becomes a FILE of that exact name on the UOSDATA disk, and
+  # /usr/local/sbin/install-uos reads them by path. Renaming a key breaks the install silently.
+  #
+  # The signed-in download link for UniFi OS Server, Linux x64. Anything that is not an https URL
+  # (this placeholder included) is treated by the guest as "not provided yet": the unit logs
+  # "UOS installer-url not set yet" and exits 0, so the VM stays healthy and simply does not install.
+  installer-url: REPLACE-ME
+  # Password set on the guest's `ubuntu` account on every boot, for `virtctl -n unifi console unifi`.
+  # THIS IS THE ONLY DOOR INTO THE GUEST. The stock Ubuntu 24.04 cloud image ships `ubuntu` locked,
+  # no key was ever installed, and an SSH key would not help: the VM's masquerade interface forwards
+  # only the ports declared in 30-virtualmachine.yaml and 22 is not among them (probed from inside
+  # virt-launcher, 2026-09-14 — the guest RSTs on 22 just as it does on 11443). Generate one with
+  #     openssl rand -base64 24
+  # Leave it as REPLACE-ME to keep the account locked; the script skips the placeholder by name.
+  console-password: REPLACE-ME
@@ -170,6 +170,27 @@ spec:
      - port: '3000'
        protocol: TCP
 ---
+# CiliumNetworkPolicy in-cluster client ingress allow (R-NET-02): gitea-allow-flux-ingress
+apiVersion: cilium.io/v2
+kind: CiliumNetworkPolicy
+metadata:
+  name: gitea-allow-flux-ingress
+  namespace: gitea
+  labels:
+    app.kubernetes.io/name: gitea
+spec:
+  endpointSelector:
+    matchLabels:
+      app.kubernetes.io/name: gitea
+  ingress:
+  - fromEndpoints:
+    - matchLabels:
+        k8s:io.kubernetes.pod.namespace: flux-system
+    toPorts:
+    - ports:
+      - port: '3000'
+        protocol: TCP
+---
 # CiliumNetworkPolicy world egress allow (egress class governs the path; R-NET-05): gitea-allow-internet-egress
 apiVersion: cilium.io/v2
 kind: CiliumNetworkPolicy
@@ -217,26 +238,6 @@ spec:
    - name: gitea
      port: 3000
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: gitea
-  namespace: gitea
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: gitea
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: gitea
-  namespaceSelector:
-    matchNames:
-    - gitea
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -251,11 +252,11 @@ spec:
  - name: gitea.slis
    rules:
    - alert: gitea-down
-      expr: up{job="gitea"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="gitea", deployment="gitea"} == 0 or absent(kube_deployment_status_replicas_available{namespace="gitea", deployment="gitea"})
      for: 5m
      labels:
        severity: critical
        service: gitea
      annotations:
        summary: gitea is down
-        description: 'gitea has been unreachable for 5m (SLI: up).'
+        description: 'gitea: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -268,6 +268,7 @@ metadata:
  annotations:
    homelab.keithjackson.dev/auth-mode: forward-auth
    homelab.keithjackson.dev/auth-groups: media-users,platform-admins
+    external-dns.alpha.kubernetes.io/controller: none
 spec:
  parentRefs:
  - name: shared
@@ -284,26 +285,6 @@ spec:
    - name: jackett
      port: 4180
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: jackett
-  namespace: jackett
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: jackett
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: jackett
-  namespaceSelector:
-    matchNames:
-    - jackett
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -318,11 +299,11 @@ spec:
  - name: jackett.slis
    rules:
    - alert: jackett-down
-      expr: up{job="jackett"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="jackett", deployment="jackett"} == 0 or absent(kube_deployment_status_replicas_available{namespace="jackett", deployment="jackett"})
      for: 5m
      labels:
        severity: critical
        service: jackett
      annotations:
        summary: jackett is down
-        description: 'jackett has been unreachable for 5m (SLI: up).'
+        description: 'jackett: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -14,9 +14,12 @@ resources:
 - nextcloud-db-backup-credentials-prod.sops.yaml
 - nextcloud-db-backup-credentials.sops.yaml
 - nextcloud-db.yaml
+- pihole-dns.yaml
 - pihole-oauth2-proxy-credentials.sops.yaml
 - pihole.yaml
+- plex-claim-secret.sops.yaml
 - plex.yaml
+- qbittorrent-bootstrap-secret.sops.yaml
 - qbittorrent-oauth2-proxy-credentials.sops.yaml
 - qbittorrent.yaml
 - semaphore-db-app.sops.yaml
@@ -158,3 +158,243 @@ spec:
  cluster:
    name: nextcloud-db
  method: barmanObjectStore
+---
+# =============================================================================
+# CNPG METRICS-EXPORTER CONNECT RECONCILER (R-OBS-01)
+#
+# THE BUG THIS CLOSES (true positive, verified live on prod 2026-09-12, and the
+# condition platform/cnpg/alerts.yaml already recorded on BOTH clusters 2026-09-06):
+# the `nextcloud` database's ACL had been narrowed out-of-band so that PUBLIC held
+# nothing, and CNPG's metrics exporter role therefore could not even CONNECT:
+#
+#   nextcloud-db-1/-2/-3, every scrape:
+#     FATAL: permission denied for database "nextcloud" (SQLSTATE 42501)
+#     DETAIL: User does not have CONNECT privilege.
+#     msg="Error collecting user query" targetDatabase=nextcloud
+#
+# CONSEQUENCE: `cnpg_last_error` = 1 on all three instances and the ENTIRE
+# cnpg_pg_stat_* / pg_settings / pg_postmaster family MISSING for this database,
+# while the scrape target still reported up=1 — a blind spot that looks like health.
+# Measured before the fix: cnpg_pg_settings_setting had 765 series for keycloak and
+# 765 for semaphore-db and ZERO for nextcloud-db. Nextcloud's database had never
+# been monitored.
+#
+# ROOT CAUSE, AND WHY ONLY THIS DATABASE. All three Cluster specs are identical in
+# their bootstrap; the difference is entirely in the live ACL:
+#
+#   nextcloud : datacl = {nextcloud=CTc/nextcloud}          <-- explicit, no PUBLIC entry
+#   keycloak  : datacl = NULL
+#   semaphore : datacl = NULL
+#
+# A NULL datacl means "PostgreSQL defaults", which include CONNECT and TEMP for
+# PUBLIC — so keycloak and semaphore let the exporter in only by inheriting PUBLIC's
+# implicit CONNECT. On `nextcloud` something ran the equivalent of
+# `REVOKE ALL ON DATABASE nextcloud FROM PUBLIC`, which MATERIALISES datacl and
+# drops the implicit PUBLIC entry with it. That REVOKE is not in this repo and not
+# in DECISIONS-LOG.md — it was applied out of band, which is exactly why a
+# git-declared fix is needed rather than another hand-run psql.
+#
+# WHY THE GRANT IS EXPLICIT RATHER THAN "RE-GRANT CONNECT TO PUBLIC": restoring
+# PUBLIC's CONNECT would undo whatever hardening that REVOKE intended and would
+# leave the exporter depending on an implicit default again — the precise fragility
+# that broke here and that keycloak/semaphore are still relying on. Naming the
+# exporter role makes the dependency explicit and survives a future REVOKE FROM
+# PUBLIC on any of the three databases.
+#
+# WHY A CronJob AND NOT A CNPG FIELD — CNPG 1.30.0's API GENUINELY CANNOT EXPRESS
+# THIS. Checked against the live CRDs on prod:
+#   * `Database` (databases.postgresql.cnpg.io) has no database-ACL field at all.
+#     `allowConnections` is the pg_database.datallowconn FLAG (open/closed to
+#     everyone), not a per-role GRANT; its only grant/revoke verbs are the `usage`
+#     lists on `fdws` and `servers`.
+#   * `spec.managed.roles` and `DatabaseRole` manage ROLE ATTRIBUTES (login,
+#     superuser, connectionLimit, ...) plus `inRoles` MEMBERSHIP. Membership is the
+#     wrong tool: the only local role holding CONNECT here is the OWNER, so
+#     `inRoles: [nextcloud]` would hand the exporter the owner's CREATE and TEMP on
+#     the database and read/write on every application table — the opposite of
+#     least privilege, to buy one CONNECT.
+#   * `bootstrap.initdb.postInitApplicationSQL` runs ONCE, at bootstrap. It cannot
+#     repair these three already-bootstrapped instances (the actual bug), and on a
+#     FRESH cluster the grant is unnecessary anyway (datacl starts NULL). Adding it
+#     would be a second mechanism that fixes nothing this one does not.
+# So the SQL has to be applied by something, and this repo already has the pattern
+# for state Flux cannot reach: the level-triggered CronJob reconciler in
+# platform/keycloak/client-secret-reconciler.yaml, whose reasoning transfers
+# verbatim — the drifted state lives inside PostgreSQL, not in a Kubernetes object,
+# so no admission or mutation policy can see it. A one-shot Job is deliberately NOT
+# used: a completed Job is never re-run, so a DB rebuild or a PITR restore would
+# silently reopen the blind spot. A loop converges instead.
+#
+# PRIVILEGE GRANTED — EXACTLY ONE, AND NOTHING ELSE:
+#   GRANT CONNECT ON DATABASE nextcloud TO cnpg_metrics_exporter;
+# Resulting ACL entry is `cnpg_metrics_exporter=c/nextcloud` — the `c` is CONNECT;
+# there is no `C` (CREATE) and no `T` (TEMPORARY). No ownership, no superuser, no
+# write, no table or schema grants. Nothing further is needed because CNPG already
+# creates this role as a member of the built-in `pg_monitor` role (verified on all
+# three prod clusters), and pg_monitor already carries the read access every
+# collector query wants — they read pg_catalog views (pg_stat_database,
+# pg_stat_archiver, pg_settings, pg_postmaster) and no application tables. Proof
+# that CONNECT alone is sufficient: after this grant, `Error collecting user query`
+# went to ZERO on all three pods, i.e. every collector query now succeeds.
+#
+# IT RUNS AS THE DATABASE OWNER, NOT AS A SUPERUSER. `enableSuperuserAccess` is off
+# on this Cluster (there is no nextcloud-db-superuser Secret), and it stays off: the
+# owner of a database holds the grant option on that database's privileges, so
+# `nextcloud` can issue this GRANT itself. Verified live before committing, by
+# running the statement under `SET ROLE nextcloud`. Credentials come from the
+# in-namespace SOPS Secret nextcloud-db-app that already exists for the app.
+#
+# NETWORKING: nextcloud-db is intentionally NOT an app-namespace (see this file's
+# header), so Kyverno generates no default-deny baseline here and this same-namespace
+# pod -> nextcloud-db-rw:5432 connection needs no rendered allow.
+#
+# THE POD LABEL IS DELIBERATELY *NOT* app.kubernetes.io/name=nextcloud-db. That
+# label is what `inheritedMetadata` stamps on the CNPG instance pods and what the
+# rendered nextcloud egress CiliumNetworkPolicy selects; reusing it here would quietly
+# make this reconciler a permitted destination for the Nextcloud app. It gets its own
+# name so that selector keeps meaning "the database".
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: nextcloud-db-exporter-grant
+  namespace: nextcloud-db
+  labels:
+    app.kubernetes.io/name: nextcloud-db-exporter-grant
+    app.kubernetes.io/part-of: nextcloud-db
+spec:
+  # Every 15 minutes, matching the keycloak reconciler's cadence. A converged
+  # database makes this one idempotent GRANT and exits; the cost is negligible, and
+  # after a rebuild or PITR restore monitoring is blind for at most one interval
+  # (well inside the alert's `for: 6h`).
+  schedule: "*/15 * * * *"
+  # A run still waiting on the primary must not be lapped by the next tick.
+  concurrencyPolicy: Forbid
+  startingDeadlineSeconds: 300
+  successfulJobsHistoryLimit: 1
+  failedJobsHistoryLimit: 3
+  jobTemplate:
+    spec:
+      backoffLimit: 2
+      activeDeadlineSeconds: 300
+      ttlSecondsAfterFinished: 3600
+      template:
+        metadata:
+          labels:
+            app.kubernetes.io/name: nextcloud-db-exporter-grant
+            app.kubernetes.io/part-of: nextcloud-db
+        spec:
+          restartPolicy: Never
+          # Talks only to PostgreSQL; its one input is a mounted Secret, so it needs
+          # no Kubernetes API access at all (R-SEC-02, least privilege).
+          automountServiceAccountToken: false
+          securityContext:
+            runAsNonRoot: true
+            # uid/gid 26 is `postgres` in the CNPG PostgreSQL image.
+            runAsUser: 26
+            runAsGroup: 26
+            seccompProfile:
+              type: RuntimeDefault
+          containers:
+            - name: grant
+              # The SAME image the instances above run, pinned to the same tag. psql
+              # is already in it and it is already present on every node, so this
+              # adds no new image and no new supply-chain surface. Keep the tag in
+              # step with spec.imageName above when Renovate bumps it.
+              image: ghcr.io/cloudnative-pg/postgresql:16.4
+              imagePullPolicy: IfNotPresent
+              command:
+                - psql
+                # -w never prompts; -X skips ~/.psqlrc; ON_ERROR_STOP makes the Job
+                # FAIL LOUDLY rather than reporting success on a refused grant.
+                - "-w"
+                - "-X"
+                - "-v"
+                - "ON_ERROR_STOP=1"
+                - "-f"
+                - /etc/grant/grant.sql
+              env:
+                # libpq connection, assembled from the owner Secret. Target the -rw
+                # Service: GRANT is a write and must reach the primary.
+                - name: PGHOST
+                  value: nextcloud-db-rw.nextcloud-db.svc.cluster.local
+                - name: PGPORT
+                  value: "5432"
+                # Connecting to the application database itself is deliberate: the
+                # owner has CONNECT on it, and a successful connection is the same
+                # check the exporter was failing.
+                - name: PGDATABASE
+                  value: nextcloud
+                - name: PGUSER
+                  valueFrom:
+                    secretKeyRef:
+                      name: nextcloud-db-app
+                      key: username
+                # Read by libpq from the environment and never logged; psql echoes
+                # no connection parameters.
+                - name: PGPASSWORD
+                  valueFrom:
+                    secretKeyRef:
+                      name: nextcloud-db-app
+                      key: password
+                - name: PGCONNECT_TIMEOUT
+                  value: "10"
+              volumeMounts:
+                - name: sql
+                  mountPath: /etc/grant
+                  readOnly: true
+              securityContext:
+                allowPrivilegeEscalation: false
+                readOnlyRootFilesystem: true
+                capabilities:
+                  drop:
+                    - ALL
+              resources:
+                requests:
+                  cpu: 10m
+                  memory: 32Mi
+                limits:
+                  memory: 128Mi
+          volumes:
+            - name: sql
+              configMap:
+                name: nextcloud-db-exporter-grant
+                defaultMode: 0444
+---
+# The desired state, as SQL. Idempotent: re-granting an existing privilege is a
+# no-op, so a converged run changes nothing. The DO block is the ASSERTION — it
+# turns "the grant did not take" into a failed Job instead of a silent success.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: nextcloud-db-exporter-grant
+  namespace: nextcloud-db
+  labels:
+    app.kubernetes.io/name: nextcloud-db-exporter-grant
+    app.kubernetes.io/part-of: nextcloud-db
+data:
+  grant.sql: |
+    -- The ONE privilege the CNPG metrics exporter is missing on this database.
+    -- CONNECT only: no CREATE, no TEMPORARY, no ownership, no table/schema grants.
+    -- Read access for the collector's pg_catalog queries already comes from the
+    -- built-in pg_monitor role, which CNPG grants this role when it creates it.
+    GRANT CONNECT ON DATABASE nextcloud TO cnpg_metrics_exporter;
+
+    -- Fail the Job if the privilege is somehow still absent, so a broken
+    -- reconciler surfaces as a failed Job rather than as a quiet blind spot.
+    -- NO PL/pgSQL, AND NOT ONE DOLLAR SIGN IN THIS FILE — DELIBERATE, including in these
+    -- comments. This assertion began life as a dollar-quoted DO block, which cannot survive
+    -- being shipped this way: the ConfigMap is rendered through Flux's postBuild
+    -- substitution, and envsubst collapses a doubled dollar into a single one. The block
+    -- reached Postgres with its opening quote halved and every Flux-reconciled run died
+    -- with a syntax error pointing at that character.
+    -- It PASSED when hand-applied with kubectl, because that path runs no envsubst — so
+    -- the defect was invisible until Flux owned the object, and three runs of Error pods
+    -- were the first sign. Escaping by doubling again would work and would also be the
+    -- next person's trap; plain SQL leaves substitution nothing to touch.
+    --
+    -- has_database_privilege() returns boolean; ::int is 1 when granted and 0 when not, so
+    -- the division raises division_by_zero and ON_ERROR_STOP=1 fails the Job. The divisor
+    -- is not a constant, so it cannot be folded away at plan time.
+    \echo 'asserting cnpg_metrics_exporter has CONNECT on database nextcloud'
+    SELECT 1 / has_database_privilege('cnpg_metrics_exporter', 'nextcloud', 'CONNECT')::int
+      AS exporter_can_connect;
@@ -0,0 +1,196 @@
+---
+# =================================================================================================
+# PiHole DNS EXPOSURE — the LAN half of split-horizon (R-DNS-01 / R-DNS-03), and NETWORK POLICY.
+# =================================================================================================
+# HAND-WRITTEN, NOT RENDERED. This file is a non-catalog app-tier unit anchored to the `pihole`
+# ServiceDefinition and placed into wave 0 by `catalog/render.py --emit-waves` via its EXTRA_UNITS
+# table (the same mechanism gitea-actions uses). It is hand-written because the ServiceDefinition
+# schema genuinely cannot express it: schemas/servicedefinition.schema.json is
+# `additionalProperties: false` and has NO field for a type=LoadBalancer Service, for a pinned
+# lbipam VIP, for a sharing key, for loadBalancerSourceRanges, or for UDP north-south exposure at
+# all. `ingressRoutes` renders HTTPRoutes on the shared Gateway, which is an L7 HTTPS terminator and
+# cannot carry DNS. The two existing L4 workloads in this repo are hand-written for exactly this
+# reason and in exactly this shape — apps/vms/unifi/50-service-l4.yaml and
+# platform/crafty/service-l4.yaml. The ANSWERS PiHole gives are declared in the catalog
+# (catalog/pihole.yaml `env`), so the only thing living outside the catalog is the exposure the
+# schema has no word for.
+#
+# WHY THIS EXISTS AT ALL: platform/coredns/coredns-custom.yaml is explicit that its split-horizon is
+# for PODS and defers LAN clients to "PiHole split-horizon" — but PiHole served no DNS. Its Service
+# was ClusterIP with ports 80 and 4180 only. The LAN half of the split-horizon that docs/09
+# (R-DNS-03) and the README's Phase 2 row both claim simply did not exist, and LAN clients ran on
+# hand-maintained per-client dnsmasq files instead. Upstream cannot substitute: the SOHO router that
+# owns this LAN strips RFC1918 answers for public domains as rebind protection (NOERROR, ANSWER 0).
+#
+# VIP: ${PIHOLE_DNS_VIP} (cluster-vars, R-ENV-02 — dev 192.168.1.56, prod 192.168.2.23), PINNED via
+# lbipam.cilium.io/ips out of the CiliumLoadBalancerIPPool `default-pool`
+# (${CILIUM_LB_POOL_START}..${CILIUM_LB_POOL_STOP}) and ARP-announced on the flat LAN by the
+# existing CiliumL2AnnouncementPolicy `default-l2` (platform-config/cilium/*). No new Cilium config
+# is needed; these Services just consume the pool. PINNING IS NOT OPTIONAL HERE: this address is
+# typed into every LAN client's resolver configuration (or handed out by the router's DHCP), so it
+# can never be allowed to move.
+#
+# ONE VIP, TWO SERVICES: a LoadBalancer Service is single-protocol-friendly, so udp/53 and tcp/53
+# split into two Services sharing one address via lbipam.cilium.io/sharing-key — the same
+# arrangement unifi and crafty use. BOTH PROTOCOLS ARE REQUIRED, not belt-and-braces: UDP is the
+# normal query path, and TCP is what a resolver falls back to for any answer that does not fit in a
+# UDP datagram and what some clients use unconditionally. A UDP-only resolver fails intermittently
+# and confusingly.
+#
+# NO external-dns ANNOTATION, DELIBERATELY. unifi and crafty both carry
+# `external-dns.alpha.kubernetes.io/hostname` so external-dns publishes their address as a PUBLIC
+# Cloudflare record. This Service must not: `pihole-dns.${BASE_DOMAIN}` is answered by PiHole itself
+# (catalog/pihole.yaml's dnsmasq override), it is an RFC1918 address that is useless in public DNS,
+# and publishing a resolver's address in a public zone invites exactly the traffic the source-range
+# filter below exists to refuse. Internal name, internal answer, no public record — which is also
+# why this change touches nothing under platform/externaldns/.
+#
+# -------------------------------------------------------------------------------------------------
+# externalTrafficPolicy: Cluster — AND WHY IT IS NOT `Local`, WHICH IS WHAT unifi AND crafty USE.
+# -------------------------------------------------------------------------------------------------
+# `Local` is the obvious choice: it preserves the client source IP and, in theory, pins the VIP to
+# the node running the backend. The second half is NOT TRUE on this cluster, and that was measured,
+# not assumed (Cilium 1.20.1, prod, 2026-09-14):
+#
+#   * Cilium's L2 announcer elects one lease holder per Service among the nodes matching the
+#     CiliumL2AnnouncementPolicy's nodeSelector — `default-l2` matches ALL linux nodes — and it does
+#     NOT filter that candidate set by which nodes hold a backend. Created fresh, the two Services
+#     landed on DIFFERENT nodes (`cilium-l2announce-pihole-pihole-dns-tcp` -> k3s-prod-3,
+#     `-udp` -> k3s-prod-2) while the pihole pod ran on k3s-prod-1.
+#   * With `Local`, a node that announces the VIP but holds no backend has nowhere to send the
+#     packet, and the query fails with ICMP port unreachable (dig: "connection refused"). On three
+#     nodes with one replica that is a 1-in-3 chance of working, drawn independently per protocol.
+#   * It does not self-heal. The lease holder keeps RENEWING after the pod moves away: a pod
+#     rescheduled from k3s-prod-1 to k3s-prod-2 left the lease on k3s-prod-1, still renewing three
+#     minutes later, with LAN resolution dead the whole time. Only deleting the Lease forced a
+#     re-election — and that re-election is random, so it may pick a backend-less node again.
+#
+# A resolver that works one time in three and stays broken after any reschedule is not a resolver.
+# `Cluster` makes every node able to serve the VIP by forwarding to wherever the pod is, which is
+# what makes this survive a reschedule and a rebuild. VERIFIED in exactly the broken arrangement
+# above — leases on k3s-prod-2 and k3s-prod-3, pod on k3s-prod-1 — udp/53, tcp/53 and recursion all
+# answering.
+#
+# THE COST, STATED PLAINLY: Cilium runs in SNAT mode here (no `loadBalancer.mode: dsr` in
+# platform/cilium/helmrelease.yaml), so a query forwarded between nodes reaches PiHole with the
+# INGRESS NODE's address as its source, not the client's. PiHole's per-client query log, per-client
+# groups and per-client rate limiting therefore see one apparent client instead of the LAN. Two
+# consequences are handled: the rate limit is disabled in catalog/pihole.yaml (otherwise the whole
+# LAN counts as one client against PiHole's 1000-queries-per-60s default and PiHole starts
+# REFUSING), and the LAN restriction is enforced in the datapath rather than by source identity —
+# see loadBalancerSourceRanges below. The fix that would restore client IPs is `loadBalancer.mode:
+# dsr` on the Cilium HelmRelease, which is a platform-wide change with an Ansible [parity] contract
+# and would also fix the same latent defect in unifi and crafty; it belongs in its own change.
+#
+# -------------------------------------------------------------------------------------------------
+# loadBalancerSourceRanges — THE LAN RESTRICTION, ENFORCED IN THE DATAPATH.
+# -------------------------------------------------------------------------------------------------
+# Cilium enforces this list in eBPF on the ingress node, on the VIP, BEFORE load-balancing and
+# before SNAT. A packet to ${PIHOLE_DNS_VIP}:53 from outside ${LAN_CIDR} is dropped by the
+# datapath — it never reaches a backend and never reaches a network policy. This is what makes
+# "LAN clients only" a real, tested restriction rather than a comment: VERIFIED by narrowing the
+# range to a /24 that excludes the test client, after which the same query that had been answering
+# stopped being answered at all, and restoring it, after which it answered again.
+#
+# It is also the layer that survives the SNAT above. A CiliumNetworkPolicy cannot express this
+# restriction once the source has been rewritten: measured on this cluster, the forwarded query
+# arrives from the ingress node's internal router address and Cilium resolves that source to the
+# reserved `world` identity, which a `fromCIDR` clause does not match even when the CIDR covers the
+# address (tried: fromCIDR ${CLUSTER_POD_CIDR}, still dropped as `world`). So the peer restriction
+# lives here, where it is actually enforceable, and the policy below restricts the PORTS.
+apiVersion: v1
+kind: Service
+metadata:
+  name: pihole-dns-udp
+  namespace: pihole
+  labels:
+    app.kubernetes.io/name: pihole
+  annotations:
+    lbipam.cilium.io/sharing-key: "pihole-dns"
+    lbipam.cilium.io/ips: "${PIHOLE_DNS_VIP}"
+spec:
+  type: LoadBalancer
+  externalTrafficPolicy: Cluster
+  loadBalancerSourceRanges:
+    - ${LAN_CIDR}
+  selector:
+    app.kubernetes.io/name: pihole
+  ports:
+    - { name: dns-udp, port: 53, targetPort: 53, protocol: UDP }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: pihole-dns-tcp
+  namespace: pihole
+  labels:
+    app.kubernetes.io/name: pihole
+  annotations:
+    lbipam.cilium.io/sharing-key: "pihole-dns"   # same key + same IP => shares the VIP with -udp
+    lbipam.cilium.io/ips: "${PIHOLE_DNS_VIP}"
+spec:
+  type: LoadBalancer
+  externalTrafficPolicy: Cluster
+  loadBalancerSourceRanges:
+    - ${LAN_CIDR}
+  selector:
+    app.kubernetes.io/name: pihole
+  ports:
+    - { name: dns-tcp, port: 53, targetPort: 53, protocol: TCP }
+---
+# =================================================================================================
+# NETWORK POLICY — a NEW ingress path from off-cluster, restricted to the two DNS ports.
+# =================================================================================================
+# The pihole namespace is default-deny on ingress (the baseline NetworkPolicy in the rendered
+# apps/wave-0/pihole.yaml: `ingress: []`). Cilium enforces the UNION of that NetworkPolicy and the
+# CiliumNetworkPolicies in the namespace, so this file ADDS one path and nothing else. Everything
+# undeclared stays denied, and the existing `pihole-allow-gateway-ingress` (Gateway -> :4180, the
+# oauth2-proxy gate in front of the admin UI) is untouched. PiHole's own :80 is NOT in this rule:
+# the admin UI stays reachable only through the Gateway and oauth2-proxy, and a LAN client that
+# talks to ${PIHOLE_DNS_VIP} on any port other than 53 gets nothing — there is no Service port for
+# it and no policy for it.
+#
+# PORTS ARE THE NARROWING HERE; THE LAN RESTRICTION IS THE SOURCE-RANGE FILTER ABOVE. The peer is
+# `world` for a mechanical reason, not a lazy one: with externalTrafficPolicy Cluster in Cilium's
+# SNAT mode a forwarded query arrives from the ingress node's internal router address, which Cilium
+# resolves to the reserved `world` identity — a `fromCIDR` clause does not match it, which was
+# measured (a fromCIDR of ${CLUSTER_POD_CIDR}, which contains that address, still produced
+# "Policy denied ... identity world" drops in `cilium-dbg monitor`). So `world` is the only peer
+# selector that can describe LAN traffic that has been through the LoadBalancer, and the set of
+# addresses that can actually BE that traffic is fixed by loadBalancerSourceRanges before this
+# policy is consulted. Together: ${LAN_CIDR} in the datapath, udp/53 + tcp/53 here.
+#
+# This is NOT wider than the precedent it follows. unifi-allow-l4-ingress and crafty-allow-ingress
+# admit `fromEntities: [world, cluster, host]` on their L4 ports with NO source-range filter at all;
+# this rule admits fewer entities (no `cluster` — in-cluster pods resolve through CoreDNS and none
+# needs PiHole on :53) on fewer ports, behind a filter those two do not have.
+#
+# WHAT REMAINS REACHABLE WITHOUT THE VIP, ACKNOWLEDGED: Cilium applies source ranges to the
+# LoadBalancer address, not to the NodePorts the same Services allocate, so a host that can route to
+# a node IP can still reach udp/53 and tcp/53 through the NodePort. On this LAN that is the same
+# population the source range admits, and nothing at the edge forwards 53 inward, so PiHole is not
+# an internet-facing open resolver. Say so out loud rather than implying the filter is total.
+#
+# `host` and `remote-node` are named explicitly because node-sourced traffic carries a reserved
+# Cilium identity that no CIDR or `world` selector matches: the kubelet's probes and the
+# node-to-node forwarding that IS the Cluster-policy datapath both need them.
+apiVersion: cilium.io/v2
+kind: CiliumNetworkPolicy
+metadata:
+  name: pihole-allow-lan-dns-ingress
+  namespace: pihole
+  labels:
+    app.kubernetes.io/name: pihole
+spec:
+  endpointSelector:
+    matchLabels:
+      app.kubernetes.io/name: pihole
+  ingress:
+    - fromEntities:
+        - world         # LAN clients, post-LoadBalancer: see the block above for why not fromCIDR
+        - host          # this node's kubelet probes
+        - remote-node   # the node-to-node hop that forwards a query to wherever the pod runs
+      toPorts:
+        - ports:
+            - { port: "53", protocol: UDP }
+            - { port: "53", protocol: TCP }
@@ -81,6 +81,15 @@ spec:
        image: pihole/pihole
        ports:
        - containerPort: 80
+        env:
+        - name: FTLCONF_dns_listeningMode
+          value: ALL
+        - name: FTLCONF_dns_upstreams
+          value: 8.8.8.8;8.8.4.4
+        - name: FTLCONF_dns_rateLimit_count
+          value: '0'
+        - name: FTLCONF_misc_dnsmasq_lines
+          value: address=/${BASE_DOMAIN}/${GATEWAY_VIP};address=/unifi.${BASE_DOMAIN}/${UNIFI_L4_VIP};address=/crafty-mc.${BASE_DOMAIN}/${CRAFTY_L4_VIP};address=/pihole-dns.${BASE_DOMAIN}/${PIHOLE_DNS_VIP}
        volumeMounts:
        - name: config
          mountPath: /data/config
@@ -223,6 +232,7 @@ metadata:
  annotations:
    homelab.keithjackson.dev/auth-mode: forward-auth
    homelab.keithjackson.dev/auth-groups: platform-admins
+    external-dns.alpha.kubernetes.io/controller: none
 spec:
  parentRefs:
  - name: shared
@@ -239,26 +249,6 @@ spec:
    - name: pihole
      port: 4180
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: pihole
-  namespace: pihole
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: pihole
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: pihole
-  namespaceSelector:
-    matchNames:
-    - pihole
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -273,11 +263,11 @@ spec:
  - name: pihole.slis
    rules:
    - alert: pihole-down
-      expr: up{job="pihole"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="pihole", deployment="pihole"} == 0 or absent(kube_deployment_status_replicas_available{namespace="pihole", deployment="pihole"})
      for: 5m
      labels:
        severity: critical
        service: pihole
      annotations:
        summary: pihole is down
-        description: 'pihole has been unreachable for 5m (SLI: up).'
+        description: 'pihole: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -0,0 +1,77 @@
+# Plex plex.tv server-claim token (WS-APPS). SOPS-encrypted (age).
+# Consumed by catalog/plex.yaml as env PLEX_CLAIM via valueFrom.secretKeyRef.
+#
+# NOTE ON THESE COMMENTS: they carry NO dollar-brace expressions, deliberately. This file is applied
+# by the apps-wave-0 Flux Kustomization, which runs envsubst over the built output, and kustomize
+# preserves body comments into that stream (see conformance/tests/l0-static/flux-postbuild-
+# substitution). A braced token quoted from the upstream shell script would be a live hazard here,
+# not prose, so the upstream conditions below are described in words.
+#
+# THIS FILE NO LONGER HOLDS THE PLACEHOLDER. Corrected 2026-09-29: the server was CLAIMED on that
+# date, and the value here is the SPENT token from that claim. It is inert and safe to leave --
+# upstream gates the exchange on PlexOnlineToken being ABSENT from /config, and it is now present on
+# the plex-config PVC, so this value is a NO-OP on every start whatever it holds. Deleting the Secret
+# would NOT be safe (see below), which is why a spent token stays here rather than being blanked.
+#
+# The claim token is SHORT-LIVED -- minutes. Read the countdown that plex.tv/claim renders when it
+# issues one; do NOT budget against a number written in this tree. Earlier revisions of this comment
+# asserted a "~4-minute TTL" as established fact with no citation, and upstream plexinc/pms-docker
+# documents no expiry at all. That uncited number was load-bearing for the whole procedure design.
+#
+# This file exists to make the Secret — and therefore the env reference — ALWAYS RESOLVABLE IN THE
+# FLUX GRAPH, not to carry a working token. Re-claiming (only needed after a /config wipe) is
+# scripted: infra/plex/claim-ship.sh, measured at ~2m45s end to end.
+#
+# WHY SHIPPING A PLACEHOLDER IS SAFE (verified against plexinc/pms-docker branch `master`, the
+# s6-overlay v2 script root/etc/cont-init.d/40-plex-first-run, cross-checked byte-identical against
+# the same file extracted from the running `plexinc/pms-docker:latest` image):
+#   - line 106 guards the claim exchange on TWO conditions: PLEX_CLAIM non-empty AND the
+#     PlexOnlineToken pref read out of /config empty. Once the server is claimed that block is
+#     skipped entirely, so whatever this Secret holds is a NO-OP on every later start. Upstream
+#     README: "If server is already logged in, this parameter is ignored."
+#   - on a still-UNCLAIMED /config, an invalid or expired token makes plex.tv answer 403 with an
+#     empty body. curl's exit status is never checked, the sed for the authentication-token element
+#     yields the empty string, and the success branch at line 120 simply does not fire. There is no
+#     else branch and no non-zero exit; the script has no `set -e` and ends by touching
+#     /.firstRunComplete and echoing, so it exits 0. The server comes up UNCLAIMED and serving.
+#     It does NOT crashloop.
+#   - the image never sets S6_BEHAVIOUR_IF_STAGE2_FAILS, whose default is 0 ("continue silently even
+#     if a cont-init script failed"), so even a hypothetical non-zero exit would not halt startup.
+# A MISSING Secret would NOT be safe: the ServiceDefinition schema's valueFrom.secretKeyRef shape
+# has no `optional` field, so an absent Secret is a hard CreateContainerConfigError. That is exactly
+# why this file is committed and listed in apps/wave-0/kustomization.yaml instead of being created
+# by hand at claim time.
+#
+# INJECTION / ROTATION (operator, not agents) — runbooks/plex-claim.md has the timed procedure:
+#   infra/devcontainer/dev.sh run sops apps/wave-0/plex-claim-secret.sops.yaml
+# Never decrypt this file into a shell, a log, or a shared terminal.
+apiVersion: v1
+kind: Secret
+metadata:
+    name: plex-claim
+    namespace: plex
+    labels:
+        app.kubernetes.io/name: plex
+type: Opaque
+stringData:
+    PLEX_CLAIM: ENC[AES256_GCM,data:nLmzeUBWRhRjUakrGiGzQpQuqZNcIYvRH6M=,iv:z0on/dArsNejNLrp3V1nSiNLFzKcREhPuMO1634CwQw=,tag:Ih23CT1JYna/5lfYQUb1Dw==,type:str]
+sops:
+    kms: []
+    gcp_kms: []
+    azure_kv: []
+    hc_vault: []
+    age:
+        - recipient: age175l8mdpdfu7hq0aml3exs3gykarwjmuvr23sq56s3wjejnyk44wsp4mfzg
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA2dWtqOVNQalZ2QlRxOXJa
+            cDc1MTdtWENkdWIxS1JId3dIU1JDSmk0ODNrCk1YUzhFWXR3bUxyV2NNcmFOakdz
+            THl1Q284dFJxTy9Rd1h0eXJJaVZtdmcKLS0tIERuN0ZFeW9zdi9aNFRYNWxmUS9s
+            QUtYdHEvN042ajNoNktOLzlYQmQrc1kK4NHozMbXVzNGYbUBRbK6a9Uw/sVPAfe6
+            RW5KWzZ4I/hloqjN3zzVISoSMieMkBGDnF5qZS5N6FqIc6/HrsDD8A==
+            -----END AGE ENCRYPTED FILE-----
+    lastmodified: "2026-09-29T06:31:16Z"
+    mac: ENC[AES256_GCM,data:62BmBAq45CD2g6LDyx+Ho4bTfrhJcaro/RB/iM+OaRc4a/D83MhjbcBL11Uz/O726inqhkvCKDJ/fFemoc50JDbtC79cYMaxrGJNjFM0sdckWrowPvh6ie7HHHUBRBaefl+gNfnc+pbvcncvRzwA4RyzcZse1wbxKfHN8FjEopE=,iv:h0cMShs3tIgnY6eruUYymYrcLFzQZLk/uXQJ/Jsd5ek=,tag:nZ9Pau7p4xWT1QCN1vv2vA==,type:str]
+    pgp: []
+    encrypted_regex: ^(data|stringData)$
+    version: 3.9.4
@@ -132,6 +132,11 @@ spec:
          value: Etc/UTC
        - name: ALLOWED_NETWORKS
          value: 10.0.0.0/8,192.168.0.0/16
+        - name: PLEX_CLAIM
+          valueFrom:
+            secretKeyRef:
+              name: plex-claim
+              key: PLEX_CLAIM
        volumeMounts:
        - name: config
          mountPath: /config
@@ -244,26 +249,6 @@ spec:
    - name: plex
      port: 32400
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: plex
-  namespace: plex
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: plex
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: plex
-  namespaceSelector:
-    matchNames:
-    - plex
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -278,11 +263,11 @@ spec:
  - name: plex.slis
    rules:
    - alert: plex-down
-      expr: up{job="plex"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="plex", deployment="plex"} == 0 or absent(kube_deployment_status_replicas_available{namespace="plex", deployment="plex"})
      for: 5m
      labels:
        severity: critical
        service: plex
      annotations:
        summary: plex is down
-        description: 'plex has been unreachable for 5m (SLI: up).'
+        description: 'plex: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -0,0 +1,60 @@
+# qBittorrent DURABLE WebUI credential (WS-APPS). SOPS-encrypted (age), decrypted in-cluster by Flux.
+#
+# WHY THIS FILE EXISTS (defect, measured on prod 2026-09-13):
+#   qBittorrent.conf on the config PVC carried NEITHER `WebUI\Username` NOR
+#   `WebUI\Password_PBKDF2`. qBittorrent 5.x treats that as "no credential set" and generates a NEW
+#   random `admin` password on EVERY process start, announcing it ONLY on stdout ("A temporary
+#   password is provided for this session: ..."). Consequences, both real: (a) Sonarr's and Radarr's
+#   saved download-client credentials stop working at the next qbittorrent pod restart, silently
+#   breaking Completed Download Handling; (b) a human operator has no stable login at all and must
+#   read the pod log after every restart.
+#
+# HOW IT IS APPLIED: catalog/qbittorrent.yaml's app container reads BOTH keys below as env
+#   (QBT_WEBUI_USERNAME / QBT_WEBUI_PASSWORD) and its `lifecycle.postStart` hook — the same idiom as
+#   gitea's break-glass admin bootstrap — DERIVES the PBKDF2-HMAC-SHA512 digest qBittorrent stores
+#   and asserts both keys into /config/qBittorrent/qBittorrent.conf on EVERY container start, then
+#   verifies the WebUI actually accepts them. Level-triggered: a pod restart, a config-PVC restore
+#   from an older backup, and a rebuild-from-git onto an EMPTY PVC all end with this SAME
+#   credential, because the hook re-asserts it on every start rather than once.
+#
+# webui-username: the WebUI account name. qBittorrent has exactly ONE local account, and `admin` is
+#   the name its own temporary-password path uses, so keeping it avoids inventing a second identity.
+# webui-password: the durable plaintext. It is ALSO what Sonarr's and Radarr's download-client
+#   entries store in their own databases (app state on their config PVCs, NOT in git — see
+#   DECISIONS-LOG), so rotating it here means re-pointing both arrs.
+#   Deliberately alphanumeric: it travels through a urlencoded WebAPI login body and two arr JSON
+#   payloads, and a shell/URL-special character in any of those is a bug waiting to happen.
+#
+# NEVER put a value in a comment: SOPS does NOT encrypt comments.
+# Recover with: infra/devcontainer/dev.sh run sops -d apps/wave-0/qbittorrent-bootstrap-secret.sops.yaml
+apiVersion: v1
+kind: Secret
+metadata:
+    name: qbittorrent-bootstrap
+    namespace: qbittorrent
+    labels:
+        app.kubernetes.io/name: qbittorrent
+type: Opaque
+stringData:
+    webui-username: ENC[AES256_GCM,data:P022nG0=,iv:MXcCXsD5hs7MAJ+OAYHkZ3pXep7XGPqeAExChoqna08=,tag:WE34mxtfQRgiwPRaDA12pQ==,type:str]
+    webui-password: ENC[AES256_GCM,data:+Lx0Ny7SBZeF/CzQYm8umntw27ewyXS7unWObpl0fCg=,iv:JkAtublBMS7SJUutAFip1XjdmsKnGe+S2E9QDT4rCJk=,tag:MYptPVgoEUEpXe5kmg1xIg==,type:str]
+sops:
+    kms: []
+    gcp_kms: []
+    azure_kv: []
+    hc_vault: []
+    age:
+        - recipient: age175l8mdpdfu7hq0aml3exs3gykarwjmuvr23sq56s3wjejnyk44wsp4mfzg
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB1aWpUY04wZHoyWVdPbGU2
+            TC9vaU5oYmhWSVh3YWVTdzkvU3Axdlh6QVFZCkV4MldaZXNyam5CejQyZStyczJ3
+            UStFd0hRQmRsNGZLVEVTRnVjWXp6SVkKLS0tICtkWlRqVGN5OWYvVnZUaHYvbEZv
+            VWtHMVdDU3hmdXo1TndLb05zQzJ0S28KfqlDBTocO0ZAKtH6ad/00EeVRqZ7WMwv
+            FP2evd5vyn95QQICWhY/LH6EKbwVVlcIlL7i9l8K3kK4Ebdk54mAyw==
+            -----END AGE ENCRYPTED FILE-----
+    lastmodified: "2026-09-13T05:23:23Z"
+    mac: ENC[AES256_GCM,data:hQ7jIgFqpNcFY5H4AfMxuslC2R/2wGmGWtghemOmTUUipSdoGdbNjWGQhxzk40lFjw6Zj2b+buOpXpg70s4xr+4feusqa2TJ3+bxAuRWmuZpTQAU2OaO5v0SdDEs3gwKm2mA3JFo/e6POm/P/kf2GIECcyU1AciZQt6ws7UJmQc=,iv:6SF0ZAuzHQThD/FGbWhFfa4dXU8hyW8jWFiDmwgfFU8=,tag:31i8HM2s/mGeS4zvFxO53Q==,type:str]
+    pgp: []
+    encrypted_regex: ^(data|stringData)$
+    version: 3.9.4
@@ -35,6 +35,33 @@ spec:
    - protocol: TCP
      port: 53
 ---
+# PersistentVolume qbittorrent-downloads - static external NFS (bulk tier)
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: qbittorrent-downloads
+  labels:
+    app.kubernetes.io/name: qbittorrent
+spec:
+  capacity:
+    storage: 9Ti
+  accessModes:
+  - ReadWriteMany
+  persistentVolumeReclaimPolicy: Retain
+  storageClassName: ''
+  mountOptions:
+  - nfsvers=4.1
+  - hard
+  - noatime
+  - timeo=600
+  - retrans=2
+  nfs:
+    server: ${BULK_NFS_SERVER}
+    path: /mnt/Storage/plex
+  claimRef:
+    namespace: qbittorrent
+    name: qbittorrent-downloads
+---
 # PVC qbittorrent-config (R-STATE)
 apiVersion: v1
 kind: PersistentVolumeClaim
@@ -51,6 +78,23 @@ spec:
    requests:
      storage: 5Gi
 ---
+# PVC qbittorrent-downloads (R-STATE)
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: qbittorrent-downloads
+  namespace: qbittorrent
+  labels:
+    app.kubernetes.io/name: qbittorrent
+spec:
+  accessModes:
+  - ReadWriteMany
+  storageClassName: ''
+  volumeName: qbittorrent-downloads
+  resources:
+    requests:
+      storage: 9Ti
+---
 # Deployment (R-PLAT-02)
 apiVersion: apps/v1
 kind: Deployment
@@ -81,9 +125,36 @@ spec:
        image: lscr.io/linuxserver/qbittorrent:5.1.2
        ports:
        - containerPort: 8080
+        env:
+        - name: PUID
+          value: '1000'
+        - name: PGID
+          value: '3000'
+        - name: QBT_WEBUI_USERNAME
+          valueFrom:
+            secretKeyRef:
+              name: qbittorrent-bootstrap
+              key: webui-username
+        - name: QBT_WEBUI_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: qbittorrent-bootstrap
+              key: webui-password
        volumeMounts:
        - name: config
          mountPath: /config
+        - name: downloads
+          mountPath: /downloads
+          subPath: downloads
+        lifecycle:
+          postStart:
+            exec:
+              command:
+              - /bin/bash
+              - -c
+              - "# Assert the durable WebUI credential in the config PVC's qBittorrent.conf, then PROVE the\n# running WebUI accepts it. Idempotent: the steady-state path writes nothing at all.\n#\n# THIS SCRIPT CONTAINS NO BRACED DOLLAR EXPANSION AT ALL, AND THAT IS DELIBERATE.\n# apps-wave-0 declares postBuild.substituteFrom cluster-vars, so Flux runs envsubst over\n# this whole manifest at RECONCILE time. The repo's escape contract (double the dollar;\n# enforced by render.py's assert_substitution_safe) makes such a form correct ON THE\n# CLUSTER \u2014 but only there:\n# envsubst collapses the doubled dollar, so the SAME text run any other way (a `kubectl\n# apply` of the golden, which runs no envsubst; a hand `kubectl exec` of the script during\n# development) keeps the doubled dollar, which bash reads as its own PID. Not hypothetical;\n# see the PORT comment below for the bug it actually caused here. Bare `$VAR` and `$(cmd)`\n# are untouched by envsubst, so they are used throughout and the script behaves IDENTICALLY\n# however it is run.\nset -u\nCONF=/config/qBittorrent/qBittorrent.conf\nSVC=/run/service/svc-qbittorrent\n# The WebUI's listening port, as a LITERAL. It matches ingressRoutes[0].port in this\n# ServiceDefinition \u2014 which is the single place the renderer takes the containerPort, the\n# Service port and the HTTPRoute backend port from \u2014 and the image exposes no WEBUI_PORT\n# env var for a lookup to read anyway.\n# It USED to be a doubled-dollar default-operator expansion of a WEBUI_PORT env var, and\n# that cost real time: run without envsubst, bash read the doubled dollar as its own PID,\n# so PORT became \"<pid>{WEBUI_PORT:-8080}\" \u2014 the brace never expanded, the digits never\n# matched. Every curl below then got an unparseable URL, returned nothing, and the hook\n# logged \"the WebUI rejected the durable\n# credential\" \u2014 having never actually asked it. That MISDIAGNOSIS is preserved in this\n# service's own marker log at 2026-09-13T05:35Z (three \"rejected\" lines, then GAVE UP,\n# against a WebUI that accepted the credential perfectly well). A literal cannot be mangled.\nPORT=8080\n# A postStart hook's stdout/stderr goes to the KUBELET, not to `kubectl logs` \u2014 so a hook\n# that only echoes is effectively silent (gitea's hits the same wall and writes a marker\n# file for it). Every outcome therefore also lands, timestamped, on the persistent config\n# volume: /config/qbittorrent-webui-cred.log is where an operator looks to see whether the\n# credential from git was asserted and accepted on this start.\nlog() {\n  echo \"[qbt-webui-cred] $*\"\n  printf '%s [qbt-webui-cred] %s\\n' \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" \"$*\" \\\n    >> /config/qbittorrent-webui-cred.log 2>/dev/null || true\n}\n\n# (1) The image's init-qbittorrent-config copies /defaults/qBittorrent.conf onto the PVC\n#     before it starts the service. Wait (bounded, ~30s) so we EDIT that file instead of\n#     racing to create one it would then not overwrite.\nn=0\nwhile [ ! -s \"$CONF\" ] && [ \"$n\" -lt 120 ]; do n=$((n + 1)); sleep 0.25; done\n\nwaited=0\nattempt=0\nwhile [ \"$attempt\" -lt 3 ]; do\n  attempt=$((attempt + 1))\n\n  # (2) Converge the conf. 0 = already correct (steady state: NO write, NO re-salt),\n  #     10 = rewritten, anything else = could not write.\n  python3 - \"$CONF\" <<'PY'\nimport base64, hashlib, hmac, os, stat, sys\n\nconf = sys.argv[1]\nuser = os.environ.get(\"QBT_WEBUI_USERNAME\", \"\")\npw = os.environ.get(\"QBT_WEBUI_PASSWORD\", \"\")\nif not user or not pw:\n    sys.stderr.write(\"[qbt-webui-cred] credential env is empty - refusing to touch the conf\\n\")\n    raise SystemExit(1)\n\n# qBittorrent's OWN parameters (base/utils/password.cpp): PBKDF2-HMAC-SHA512, 100000\n# iterations, 16-byte random salt, 64-byte digest, stored as\n#   WebUI\\Password_PBKDF2=\"@ByteArray(<base64 salt>:<base64 digest>)\"\n# Get any one of them wrong and the app simply rejects every login.\nITERATIONS, DIGEST_LEN, SALT_LEN = 100000, 64, 16\nUKEY, PKEY, SECTION = \"WebUI\\\\Username\", \"WebUI\\\\Password_PBKDF2\"\
+                , \"[Preferences]\"\n\ndef matches(raw):\n    \"\"\"True iff the stored digest is one OUR password produces (salt is read from it).\"\"\"\n    v = raw.strip().strip('\"')\n    if v.startswith(\"@ByteArray(\") and v.endswith(\")\"):\n        v = v[len(\"@ByteArray(\"):-1]\n    try:\n        salt_b64, digest_b64 = v.split(\":\", 1)\n        salt = base64.b64decode(salt_b64, validate=True)\n        digest = base64.b64decode(digest_b64, validate=True)\n    except Exception:\n        return False\n    if not salt or not digest:\n        return False\n    return hmac.compare_digest(\n        hashlib.pbkdf2_hmac(\"sha512\", pw.encode(), salt, ITERATIONS, len(digest)), digest)\n\ntry:\n    lines = open(conf, encoding=\"utf-8\", errors=\"replace\").read().splitlines()\nexcept FileNotFoundError:\n    lines = []\n\ndef value_of(key):\n    for i, line in enumerate(lines):\n        if line.startswith(key + \"=\"):\n            return i, line.split(\"=\", 1)[1]\n    return -1, None\n\nui, uval = value_of(UKEY)\npi, pval = value_of(PKEY)\nif uval == user and pval is not None and matches(pval):\n    raise SystemExit(0)          # converged - leave the file (and its salt) alone\n\nsalt = os.urandom(SALT_LEN)\ndigest = hashlib.pbkdf2_hmac(\"sha512\", pw.encode(), salt, ITERATIONS, DIGEST_LEN)\nstored = base64.b64encode(salt).decode() + \":\" + base64.b64encode(digest).decode()\ndesired = [UKEY + \"=\" + user, PKEY + '=\"@ByteArray(' + stored + ')\"']\n\nout = [line for i, line in enumerate(lines) if i not in (ui, pi)]\nif SECTION in out:\n    at = out.index(SECTION) + 1\nelse:\n    if out and out[-1].strip():\n        out.append(\"\")\n    out.append(SECTION)\n    at = len(out)\nout[at:at] = desired\n\ntry:\n    os.makedirs(os.path.dirname(conf) or \".\", exist_ok=True)\n    tmp = conf + \".webui-cred.new\"\n    with open(tmp, \"w\", encoding=\"utf-8\") as fh:\n        fh.write(\"\\n\".join(out) + \"\\n\")\n        fh.flush()\n        os.fsync(fh.fileno())\n    # This hook runs as ROOT; the service runs as PUID:PGID. A root-owned 0600 conf would\n    # cost the app the ability to save its own settings, so carry the ownership over.\n    try:\n        st = os.stat(conf)\n        os.chown(tmp, st.st_uid, st.st_gid)\n        os.chmod(tmp, stat.S_IMODE(st.st_mode))\n    except FileNotFoundError:\n        os.chown(tmp, int(os.environ.get(\"PUID\", \"1000\")),\n                 int(os.environ.get(\"PGID\", \"1000\")))\n        os.chmod(tmp, 0o664)\n    os.replace(tmp, conf)        # atomic: the app never reads a half-written conf\nexcept OSError as exc:\n    sys.stderr.write(\"[qbt-webui-cred] cannot write %s: %s\\n\" % (conf, exc))\n    raise SystemExit(1)\nraise SystemExit(10)\nPY\n  rc=$?\n\n  if [ \"$rc\" = 0 ]; then\n    log \"conf already holds the durable credential for '$QBT_WEBUI_USERNAME' (no write)\"\n  elif [ \"$rc\" = 10 ]; then\n    log \"asserted WebUI Username + Password_PBKDF2 into $CONF\"\n    # postStart runs CONCURRENTLY with the s6 init chain, so qbittorrent-nox may ALREADY\n    # have read the old, credential-less conf and be serving a random temporary password.\n    # Restart the SUPERVISED SERVICE (not the pod) so it re-reads what was just written.\n    # Nothing to do when the service has not started yet - it will read the new file.\n    # Its own counter, NOT the shared `waited` API budget: sharing one counter is how the\n    # 2026-09-13 failure spent the entire verification budget before the first login and\n    # then fired attempts 2 and 3 with no wait left at all.\n    sv=0\n    while [ \"$sv\" -lt 60 ] && [ \"$(s6-svstat -u \"$SVC\" 2>/dev/null)\" != \"true\" ]; do\n      sv=$((sv + 1)); sleep 1\n    done\n    if [ \"$(s6-svstat -u \"$SVC\" 2>/dev/null)\" = \"true\" ]; then\n      log \"qbittorrent-nox was already running - restarting it to load the credential\"\n      s6-svc -r \"$SVC\" || log \"s6-svc -r failed (continuing to verify anyway)\"\n      sleep 3\n    fi\n  else\n    log \"FAILED to write the credential into $CONF (helper exit $rc). The WebUI will keep\" >&2\n    log \"minting a random password\
+                \ every start and BOTH arrs will break. Fix and restart.\" >&2\n    exit 0\n  fi\n\n  # (3) GROUND TRUTH: the WebUI itself must accept it. Wait for the API to answer at ALL\n  #     (shared ~120s budget across attempts), then spend exactly ONE login per attempt -\n  #     at most 3 rejected logins, which stays under qBittorrent's default ban threshold.\n  #\n  # \"THE API NEVER ANSWERED\" IS A DIFFERENT FAULT FROM \"THE PASSWORD WAS REJECTED\", and\n  # conflating them is what made this hook lie once already (see the PORT comment). An\n  # unreachable WebUI is reported as unreachable, and the hook stops rather than spending\n  # its remaining login attempts to produce two more identical wrong diagnoses.\n  api_ok=0\n  while [ \"$waited\" -lt 120 ]; do\n    code=$(curl -s -o /dev/null -m 3 -w '%{http_code}' \"http://127.0.0.1:$PORT/\" 2>/dev/null)\n    if [ -n \"$code\" ] && [ \"$code\" != \"000\" ]; then api_ok=1; break; fi\n    waited=$((waited + 1)); sleep 1\n  done\n  if [ \"$api_ok\" != 1 ]; then\n    log \"the WebUI never answered on 127.0.0.1:$PORT within the wait budget, so the\" >&2\n    log \"credential in $CONF is UNVERIFIED. This is NOT a rejected password - it was\" >&2\n    log \"never submitted. Do not rotate the credential on the strength of this line.\" >&2\n    exit 0\n  fi\n  body=$(curl -sS -m 10 \\\n           --data-urlencode \"username=$QBT_WEBUI_USERNAME\" \\\n           --data-urlencode \"password=$QBT_WEBUI_PASSWORD\" \\\n           \"http://127.0.0.1:$PORT/api/v2/auth/login\" 2>/dev/null)\n  if [ \"$body\" = \"Ok.\" ]; then\n    log \"VERIFIED: the WebUI accepts the durable credential for '$QBT_WEBUI_USERNAME'\"\n    exit 0\n  fi\n  log \"WebUI rejected the durable credential (login said '$body')\" >&2\n  # A rejection when the conf was ALREADY converged (rc=0, nothing written) can only mean\n  # the running qbittorrent-nox is serving something it read from an EARLIER conf, so\n  # rewriting the same bytes on the next attempt would change nothing. The remedy is to\n  # make the process RE-READ the file, so restart the supervised service and let the next\n  # attempt re-verify. Without this the retry loop could never change its own outcome.\n  if [ \"$(s6-svstat -u \"$SVC\" 2>/dev/null)\" = \"true\" ]; then\n    log \"restarting qbittorrent-nox so it re-reads $CONF, then re-verifying\" >&2\n    s6-svc -r \"$SVC\" || log \"s6-svc -r failed (continuing to verify anyway)\" >&2\n    sleep 3\n  fi\ndone\n\nlog \"GAVE UP after $attempt attempts: the WebUI does not accept the credential from git.\" >&2\n# A postStart hook MUST exit 0 - a non-zero exit makes the kubelet KILL the container\n# (FailedPostStartHook -> CrashLoopBackOff), turning a credential fault into an outage.\n# Both failure paths above therefore log LOUDLY and exit 0; the `up` SLI still watches the\n# app, and the arrs' own download-client health check surfaces a broken credential.\nexit 0\n"
      - name: oauth2-proxy
        image: quay.io/oauth2-proxy/oauth2-proxy:v7.8.1
        imagePullPolicy: IfNotPresent
@@ -149,10 +220,15 @@ spec:
            port: http
          initialDelaySeconds: 5
          periodSeconds: 15
+      securityContext:
+        fsGroup: 3000
      volumes:
      - name: config
        persistentVolumeClaim:
          claimName: qbittorrent-config
+      - name: downloads
+        persistentVolumeClaim:
+          claimName: qbittorrent-downloads
 ---
 # Service
 apiVersion: v1
@@ -268,6 +344,7 @@ metadata:
  annotations:
    homelab.keithjackson.dev/auth-mode: forward-auth
    homelab.keithjackson.dev/auth-groups: media-users,platform-admins
+    external-dns.alpha.kubernetes.io/controller: none
 spec:
  parentRefs:
  - name: shared
@@ -284,26 +361,6 @@ spec:
    - name: qbittorrent
      port: 4180
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: qbittorrent
-  namespace: qbittorrent
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: qbittorrent
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: qbittorrent
-  namespaceSelector:
-    matchNames:
-    - qbittorrent
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -318,11 +375,11 @@ spec:
  - name: qbittorrent.slis
    rules:
    - alert: qbittorrent-down
-      expr: up{job="qbittorrent"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="qbittorrent", deployment="qbittorrent"} == 0 or absent(kube_deployment_status_replicas_available{namespace="qbittorrent", deployment="qbittorrent"})
      for: 5m
      labels:
        severity: critical
        service: qbittorrent
      annotations:
        summary: qbittorrent is down
-        description: 'qbittorrent has been unreachable for 5m (SLI: up).'
+        description: 'qbittorrent: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -0,0 +1,267 @@
+# promtool rule-unit tests for the wave-0 per-app `<app>-down` SLI rules.
+# Manifests under test: every PrometheusRule in apps/wave-0/ — gitea, jackett, pihole, plex,
+# qbittorrent (container/Deployment) and vm-demo (KubeVirt VMI). The harness discovers this file by
+# the SUITE convention (`<dir>/tests/*.test.yaml`) and flattens those RENDERED manifests, so these
+# tests run against the exact expressions Flux applies, never a copy.
+#
+# Run with: platform/monitoring/tests/run.sh apps/wave-0/tests/app-slis.test.yaml
+#           (the merge gate runs the same harness via
+#            conformance/tests/l0-static/alert-rules-unit-tested)
+#
+# WHY THESE EXIST. Until 2026-09-13 every one of these rules read `up{job="<app>"} == 0` while the
+# rendered ServiceMonitor named a Service port (`metrics`) that no rendered Service defined. The
+# monitor discovered ZERO targets, so no `up{job="<app>"}` series existed and the rule could not
+# fire — on prod, `count by (job) (up)` listed 24 jobs and not one of the twelve appeared.
+# `PrometheusTargetsMissing` could not see it either: a target that was never discovered has no `up`
+# series to be 0. The rules now read kube-state-metrics / kubevirt series that DO exist for these
+# workloads (verified on prod), and every rule below is pinned in BOTH directions:
+#   * QUIET on the healthy state -> it is not permanently firing;
+#   * FIRING when the workload has no ready replica -> it is not inert;
+#   * FIRING when the signal is ABSENT -> the failure mode that produced this whole defect class
+#     (a rule that goes quiet because its series vanished) is itself alerted on.
+#
+# CLOCK/`for` CONVENTION: sample interval 1m, series 21 samples long, evaluated at 10m — comfortably
+# past every rule's `for: 5m` and well inside Prometheus' 5m lookback.
+rule_files:
+  - generated.rules.yaml
+
+evaluation_interval: 1m
+
+tests:
+  # ===========================================================================================
+  # 1. HEALTHY WAVE-0 (what prod looks like right now) -> every rule SILENT.
+  #    This is the "not permanently firing" half. It is also the test that catches a mis-spelled
+  #    label: get `deployment=` wrong and the `== 0` half matches nothing while the `absent()` half
+  #    matches everything, so this test goes red instead of the rule going quietly wrong.
+  # ===========================================================================================
+  - interval: 1m
+    name: wave-0 healthy - every app has a ready replica, the demo VM runs - all quiet
+    input_series:
+      - series: 'kube_deployment_status_replicas_available{namespace="gitea", deployment="gitea"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="jackett", deployment="jackett"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="pihole", deployment="pihole"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="plex", deployment="plex"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="qbittorrent", deployment="qbittorrent"}'
+        values: '1+0x20'
+      - series: 'kubevirt_vmi_info{namespace="vm-demo", name="vm-demo", phase="running", node="k3s-prod-1"}'
+        values: '1+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: gitea-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: jackett-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: pihole-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: plex-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: qbittorrent-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: vm-demo-down
+        exp_alerts: []
+
+  # ===========================================================================================
+  # 2. EACH APP DOWN IN TURN (0 available replicas) -> ONLY that app's rule fires.
+  #    The per-app isolation matters: a rule that forgot its `namespace=`/`deployment=` matchers
+  #    would light up every app at once and be useless for routing.
+  # ===========================================================================================
+  - interval: 1m
+    name: wave-0 plex has no available replica - only plex-down fires
+    input_series:
+      - series: 'kube_deployment_status_replicas_available{namespace="gitea", deployment="gitea"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="jackett", deployment="jackett"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="pihole", deployment="pihole"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="plex", deployment="plex"}'
+        values: '0+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="qbittorrent", deployment="qbittorrent"}'
+        values: '1+0x20'
+      - series: 'kubevirt_vmi_info{namespace="vm-demo", name="vm-demo", phase="running"}'
+        values: '1+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: plex-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: plex
+              namespace: plex
+              deployment: plex
+            exp_annotations:
+              summary: "plex is down"
+              description: "plex: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: gitea-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: jackett-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: pihole-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: qbittorrent-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: vm-demo-down
+        exp_alerts: []
+    # Before `for: 5m` has elapsed the rule must be PENDING, not firing — proof the 5m is real and
+    # a single scrape blip does not page anyone.
+    promql_expr_test:
+      - expr: 'kube_deployment_status_replicas_available{namespace="plex", deployment="plex"} == 0 or absent(kube_deployment_status_replicas_available{namespace="plex", deployment="plex"})'
+        eval_time: 2m
+        exp_samples:
+          - labels: 'kube_deployment_status_replicas_available{deployment="plex", namespace="plex"}'
+            value: 0
+
+  - interval: 1m
+    name: wave-0 gitea/jackett/pihole/qbittorrent each down - each own rule fires
+    input_series:
+      - series: 'kube_deployment_status_replicas_available{namespace="gitea", deployment="gitea"}'
+        values: '0+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="jackett", deployment="jackett"}'
+        values: '0+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="pihole", deployment="pihole"}'
+        values: '0+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="plex", deployment="plex"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="qbittorrent", deployment="qbittorrent"}'
+        values: '0+0x20'
+      - series: 'kubevirt_vmi_info{namespace="vm-demo", name="vm-demo", phase="running"}'
+        values: '1+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: gitea-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: gitea
+              namespace: gitea
+              deployment: gitea
+            exp_annotations:
+              summary: "gitea is down"
+              description: "gitea: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: jackett-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: jackett
+              namespace: jackett
+              deployment: jackett
+            exp_annotations:
+              summary: "jackett is down"
+              description: "jackett: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: pihole-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: pihole
+              namespace: pihole
+              deployment: pihole
+            exp_annotations:
+              summary: "pihole is down"
+              description: "pihole: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: qbittorrent-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: qbittorrent
+              namespace: qbittorrent
+              deployment: qbittorrent
+            exp_annotations:
+              summary: "qbittorrent is down"
+              description: "qbittorrent: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: plex-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: vm-demo-down
+        exp_alerts: []
+
+  # ===========================================================================================
+  # 3. THE SIGNAL VANISHES -> the rule FIRES. This is the defect class itself, asserted on.
+  #    The old `up{job=...} == 0` rule had exactly this shape of hole and was silent for it. Here
+  #    the Deployment series for plex is simply not in the input at all, and plex-down must still
+  #    fire (via the `absent()` half), with the labels the selector's equality matchers carry.
+  # ===========================================================================================
+  - interval: 1m
+    name: wave-0 plex Deployment series ABSENT (never scraped / workload gone) - plex-down fires
+    input_series:
+      - series: 'kube_deployment_status_replicas_available{namespace="gitea", deployment="gitea"}'
+        values: '1+0x20'
+      - series: 'kubevirt_vmi_info{namespace="vm-demo", name="vm-demo", phase="running"}'
+        values: '1+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: plex-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: plex
+              namespace: plex
+              deployment: plex
+            exp_annotations:
+              summary: "plex is down"
+              description: "plex: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: gitea-down
+        exp_alerts: []
+
+  # ===========================================================================================
+  # 4. THE VM: a VMI carries no replica count, so liveness is the EXISTENCE of a running-phase
+  #    series. Two ways to be down, both asserted: the VMI is gone entirely, and the VMI exists in
+  #    some OTHER phase. The second is the one a naive `kubevirt_vmi_info == 1` would miss, and it
+  #    is why the phase value is matched — LOWERCASE `running`, the value KubeVirt actually writes
+  #    (a capital-R matcher selects nothing and would be just as inert).
+  # ===========================================================================================
+  - interval: 1m
+    name: wave-0 demo VM has no running-phase VMI - vm-demo-down fires
+    input_series:
+      - series: 'kube_deployment_status_replicas_available{namespace="gitea", deployment="gitea"}'
+        values: '1+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: vm-demo-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: vm-demo
+              namespace: vm-demo
+              name: vm-demo
+              phase: running
+            exp_annotations:
+              summary: "vm-demo is down"
+              description: "vm-demo: no KubeVirt VMI in phase running for 5m (SLI: up, via kubevirt_vmi_info)."
+
+  - interval: 1m
+    name: wave-0 demo VM exists but is Failed, not running - vm-demo-down still fires
+    input_series:
+      - series: 'kubevirt_vmi_info{namespace="vm-demo", name="vm-demo", phase="failed"}'
+        values: '1+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: vm-demo-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: vm-demo
+              namespace: vm-demo
+              name: vm-demo
+              phase: running
+            exp_annotations:
+              summary: "vm-demo is down"
+              description: "vm-demo: no KubeVirt VMI in phase running for 5m (SLI: up, via kubevirt_vmi_info)."
@@ -115,26 +115,6 @@ spec:
  - toEntities:
    - world
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: vm-demo
-  namespace: vm-demo
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: vm-demo
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: vm-demo
-  namespaceSelector:
-    matchNames:
-    - vm-demo
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -149,11 +129,11 @@ spec:
  - name: vm-demo.slis
    rules:
    - alert: vm-demo-down
-      expr: up{job="vm-demo"} == 0
+      expr: absent(kubevirt_vmi_info{namespace="vm-demo", name="vm-demo", phase="running"})
      for: 5m
      labels:
        severity: critical
        service: vm-demo
      annotations:
        summary: vm-demo is down
-        description: 'vm-demo has been unreachable for 5m (SLI: up).'
+        description: 'vm-demo: no KubeVirt VMI in phase running for 5m (SLI: up, via kubevirt_vmi_info).'
@@ -4,7 +4,13 @@
 # against Gitea. Flux decrypts it via the sops-age key at reconcile (apps Kustomization
 # decryption is wired in clusters/dev/kustomization.yaml). Rotate by resetting the token
 # in Gitea (admin -> actions -> runners) and re-encrypting a fresh value here.
-# Recover/inspect: infra/devcontainer/dev.sh run sops -d apps/gitea-actions-runner-secret.sops.yaml
+# ROTATE: ./infra/gitea/runner-token-rotate.sh -- it mints a fresh instance-level token from the
+# Gitea API and writes it here via `sops set`, without the value ever being printed.
+# Do NOT `sops -d` this file into a terminal, a log, or an agent transcript. To check only that
+# it still decrypts, redirect: `sops -d <file> > /dev/null`.
+# NOTE: a fresh token alone may not re-register the runner. act_runner registers ONCE and keeps
+# its identity in /data/.runner on the act-runner-data PVC; if Gitea no longer holds a matching
+# row it skips registration silently. Clearing that PVC is what forces a real re-registration.
 apiVersion: v1
 kind: Secret
 metadata:
@@ -14,7 +20,7 @@ metadata:
        app.kubernetes.io/name: act-runner
 type: Opaque
 stringData:
-    token: ENC[AES256_GCM,data:W48mEtBqGeukX13lMhrhrer+zB21cLVp0acy3m1Xy/oo89DqO8FX/Q==,iv:wfTUU7RiFLdEc1fmEFS9DfE2SmGCFLPK17m0IKspft0=,tag:UhoXA47p7386KHcYNbPzCg==,type:str]
+    token: ENC[AES256_GCM,data:f574mAUkLvMGq0TYycwCd4tduMuBgQLiTg/140kuRDgFUYYm1ZoSjQ==,iv:Tn7gFWBLm2hHk/BbfVX7qIZegwZp9ah1cMou5i2O91E=,tag:TkdSiMI4sdCNn2JuN++Pig==,type:str]
 sops:
    kms: []
    gcp_kms: []
@@ -30,8 +36,8 @@ sops:
            MDZLUE52QzJXbFlrNWxOcVhJbDNnY00KxCpFkbhhCuk4Fa8CC3C4+R9AcsUnaXQR
            UjAfwKFoXAneXUih7TTXMbR/6+VgQBww5Bmwpn7jVLnzP0N0pIZVTA==
            -----END AGE ENCRYPTED FILE-----
-    lastmodified: "2026-08-26T04:48:14Z"
-    mac: ENC[AES256_GCM,data:b99/zkL332RIT3FYBa1sR3o9+pwlmrUgKvVHawbjWYSJZ7ERUfO+LXuhKJ0HKrp6i1JfkurZlRO27iBcfrBisAXS9KLaqmsCJf4kKfFc4skANrmKCzprrXUmZexr1uiE8eDUzjNCLNxSCZfnFR6d/AkMXJqi6Hsj9/O+wH2lWsc=,iv:3DIPszSdxK81ERO3o/nTs33qQYHaAKLNcGP4qlZViFc=,tag:/B6VKkzMUwh0byNUicS5wQ==,type:str]
+    lastmodified: "2026-09-29T05:48:35Z"
+    mac: ENC[AES256_GCM,data:nobqr794nrdRYFrd8Ct8bw9M8NtftJXawRGk9zrL+pTWahwlWrwXVtOAxMGEPVojz3WemsxTJESzmzy0gcT1QcrjpYTsF2MVHcr6+umk8q9gAh2enyxy/0QkYiSt6XjvRVqfqleLanEkeIq1FPf2zhSLSJaiw4/oZTfkCHD1/Zg=,iv:JxaP0htmGcvE4ZU1YAmGF4A6JkejV29NNygyMl1OKF8=,tag:G70NvcPyVuagXhugWoUfTw==,type:str]
    pgp: []
    encrypted_regex: ^(data|stringData)$
    version: 3.9.4
@@ -99,70 +99,79 @@ spec:
      # CI holds no cluster credentials — do not mount a SA token into the runner or
      # (via the shared netns) the job containers (R-SEC-02, docs/14).
      automountServiceAccountToken: false
+      # ---- Docker-in-Docker: the job executor daemon (privileged) -------------------
+      #
+      # NATIVE SIDECAR (k3s v1.36; sidecar containers are GA). It is an initContainer with
+      # `restartPolicy: Always`, which means: it starts BEFORE the regular containers, keeps
+      # running alongside them, and is terminated after them. kubelet holds `runner` until
+      # this container's startupProbe passes, so the ordering is enforced by the kubelet
+      # instead of hand-rolled shell in the runner.
+      #
+      # This REPLACES two bounded wait-loops that used to live in the runner's `command:`.
+      # Deleting them also deletes an envsubst hazard: clusters/base/apps-wave-1.yaml runs
+      # postBuild substitution over this ENTIRE manifest, comments included, and those loops
+      # depended on bare dollar-names surviving it untouched. There is now no shell here at
+      # all, so there is nothing to escape or mis-escape.
+      #
+      # WHY THE PROBE IS `exec docker ... info` AND NOT `tcpSocket`. A tcpSocket probe would
+      # re-open the exact gap the old Stage 1 existed to close: dockerd writes the TLS certs
+      # and only THEN begins listening, so the port can accept a connection while the certs
+      # are absent or incomplete -- and act_runner hard-exits on a missing
+      # /certs/client/ca.pem. A full TLS-verified `docker info` proves BOTH that the certs
+      # are usable and that the daemon answers.
+      #
+      # CORRECTION (measured 2026-09-29, after this conversion shipped): the commit that
+      # introduced this claimed the conversion would REMOVE the one-per-start dockerd line
+      # `http: TLS handshake error from 127.0.0.1: EOF`. IT DOES NOT. Exactly one still
+      # appears, immediately after "API listen on [::]:2376" -- it is now this probe's FIRST
+      # attempt, landing microseconds after dockerd begins listening and cut off by
+      # timeoutSeconds: 1. The next poll succeeds. It is cosmetic, exactly as cosmetic as it
+      # was before, and deliberately NOT chased: raising timeoutSeconds to hide one benign
+      # startup line would slow every subsequent poll. Left documented rather than silenced.
+      #
+      # periodSeconds 1 x failureThreshold 60 preserves the previous 60s cap.
+      initContainers:
+        - name: dind
+          restartPolicy: Always   # <- this field is what makes it a SIDECAR
+          image: docker:27-dind
+          securityContext:
+            privileged: true
+          env:
+            # Generate + publish TLS certs into the shared emptyDir; dockerd then listens
+            # on tcp://0.0.0.0:2376 (TLS) which the runner reaches at localhost:2376.
+            - name: DOCKER_TLS_CERTDIR
+              value: /certs
+          volumeMounts:
+            - name: certs
+              mountPath: /certs
+            - name: dind-storage
+              mountPath: /var/lib/docker
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              memory: 2Gi
+          startupProbe:
+            exec:
+              command:
+                - docker
+                - --host=tcp://127.0.0.1:2376
+                - --tlsverify
+                - --tlscacert=/certs/client/ca.pem
+                - --tlscert=/certs/client/cert.pem
+                - --tlskey=/certs/client/key.pem
+                - info
+            periodSeconds: 1
+            failureThreshold: 60
      containers:
        # ---- act_runner: registers with Gitea, dispatches jobs to the DinD daemon ----
        - name: runner
          image: gitea/act_runner:0.2.11
-          # TWO-STAGE BOUNDED WAIT on the DinD sidecar, then exec the image's normal
-          # entrypoint (/sbin/tini -- /opt/act/run.sh), which registers-from-env on first
-          # boot and runs `act_runner daemon`.
-          #
-          # STAGE 1 — the certs must EXIST: act_runner reads /certs/client/ca.pem at startup
-          #   and hard-exits if it is missing (a startup race against the sidecar).
-          # STAGE 2 — the daemon must actually ACCEPT a connection: the cert FILE appearing is
-          #   necessary but NOT sufficient. dockerd writes the certs and only THEN begins
-          #   listening on :2376, so a runner that proceeds on the file alone still hard-exits
-          #   with "cannot ping the docker daemon at tcp://localhost:2376" — observed
-          #   crashlooping 11 times in ~8 minutes on a fresh pod after a node bounce.
-          # Both loops are bounded (60 x 1s) and exit 1 on timeout, so a genuinely dead sidecar
-          # surfaces as a CrashLoopBackOff with a clear message instead of hanging forever.
-          #
-          # ENVSUBST SAFETY — the BARE $i / $j below are CORRECT. Do not "tidy" them into the
-          #   braced form or the double-dollar form; both are wrong here, for different reasons.
-          #   clusters/base/apps-wave-1.yaml carries postBuild.substituteFrom cluster-vars, so
-          #   Flux envsubst runs over this ENTIRE manifest — YAML comments very much included.
-          #   Its contract (drone/envsubst; the same one spelled out in clusters/base/apps-vms.yaml,
-          #   and re-verified against this exact file with `flux envsubst`, flux v2.4.0) is:
-          #     - A bare  $name  is NOT a reference to envsubst: it passes through untouched, and
-          #       that holds even when the name IS set in cluster-vars. So $i and $j reach the
-          #       cluster verbatim and both 60s bounds below are real, enforced bounds.
-          #     - $((i + 1))  is likewise untouched: "(" cannot begin a variable name.
-          #     - A BRACED dollar-name IS a reference and gets replaced — with the empty string
-          #       when the name is unset. One of those here would make a bound read [ "" -ge 60 ],
-          #       which errors, short-circuits the &&, and silently turns the wait UNBOUNDED.
-          #     - A DOUBLE-dollar braced name is envsubst's escape and survives as the braced
-          #       form — still wrong for us, because on any path where envsubst does NOT run
-          #       (a plain `kustomize build` or `kubectl apply -k` of this directory) the shell
-          #       reads that leading double-dollar as its own PID, so a bound would compare a
-          #       string like 1234{i} against 60. The bare form is the only spelling that is
-          #       correct on BOTH paths.
-          #     - A braced name containing punctuation is a HARD ERROR ("unable to parse variable
-          #       name") that fails this whole Kustomization — and this Kustomization gates every
-          #       merge in the repo. So never write one anywhere in this file, INCLUDING in a
-          #       comment. That is why this note names the three forms in words rather than
-          #       showing them: an earlier draft of it spelled them out literally and broke
-          #       `flux envsubst` on the file. (Same trap the indexed-expansion warning in
-          #       clusters/base/apps-vms.yaml describes.)
-          command:
-            - /bin/sh
-            - -c
-            - |
-              # Stage 1: the sidecar's TLS client certs must appear in the shared emptyDir.
-              i=0
-              until [ -f /certs/client/ca.pem ]; do
-                i=$((i + 1))
-                [ "$i" -ge 60 ] && { echo "dind certs never appeared" >&2; exit 1; }
-                echo "waiting for dind TLS certs ($i)"; sleep 1
-              done
-              # Stage 2: dockerd must actually accept a connection on :2376. busybox nc in this
-              # Alpine-based image (gitea/act_runner:0.2.11) supports -z (scan) and -w (timeout).
-              j=0
-              until nc -z -w1 127.0.0.1 2376; do
-                j=$((j + 1))
-                [ "$j" -ge 60 ] && { echo "dind daemon never accepted a connection on 2376" >&2; exit 1; }
-                echo "waiting for dind daemon on :2376 ($j)"; sleep 1
-              done
-              exec /sbin/tini -- /opt/act/run.sh
+          # No `command:` override. The image's own entrypoint (/sbin/tini -- /opt/act/run.sh)
+          # registers from env on first boot and runs `act_runner daemon`. The two wait-loops
+          # that used to live here are gone: kubelet now holds this container until the dind
+          # sidecar's startupProbe passes (see initContainers above).
          env:
            - name: GITEA_INSTANCE_URL
              value: https://gitea.${BASE_DOMAIN}
@@ -198,52 +207,6 @@ spec:
              memory: 128Mi
            limits:
              memory: 512Mi
-        # ---- Docker-in-Docker: the job executor daemon (privileged) ----
-        #
-        # FOLLOW-UP (deliberately NOT bundled into the readiness fix above — own change):
-        #   Convert this container into a NATIVE SIDECAR and delete both shell wait-loops.
-        #   k3s is now v1.36, where sidecar containers are GA, so kubelet can enforce the
-        #   ordering that the loops above hand-roll — which also removes the envsubst hazard
-        #   from this file entirely (no shell, no $i/$j, nothing to escape or mis-escape).
-        #   Shape to build:
-        #     1. Move this whole container into `initContainers:` as the FIRST entry.
-        #     2. Add `restartPolicy: Always` to it. That single field is what makes an
-        #        initContainer a sidecar: it starts before the regular containers, keeps
-        #        running alongside them, and is terminated after them.
-        #     3. Give it a `startupProbe` that succeeds only when dockerd accepts a TLS
-        #        connection — e.g. `exec` a `docker -H tcp://127.0.0.1:2376 --tlsverify
-        #        --tlscacert /certs/client/ca.pem --tlscert /certs/client/cert.pem
-        #        --tlskey /certs/client/key.pem info`. Do NOT use a bare `tcpSocket` probe:
-        #        it would re-open the same "port accepting but TLS/certs not ready" gap that
-        #        Stage 1 above exists to close. `periodSeconds: 1` + `failureThreshold: 60`
-        #        preserves today's 60s cap.
-        #     4. kubelet then holds the `runner` container until that startupProbe passes, so
-        #        `runner` can drop its `command:` override completely and run the image's
-        #        default entrypoint.
-        #   Why it is a separate change: this Deployment is the ENFORCED MERGE GATE for this
-        #   entire repository. If the conversion is wrong, nothing can merge — so it must land
-        #   alone, where the failure is unambiguous and not entangled with anything else, and
-        #   only after a real workflow run has been observed green on the converted pod.
-        - name: dind
-          image: docker:27-dind
-          securityContext:
-            privileged: true
-          env:
-            # Generate + publish TLS certs into the shared emptyDir; dockerd then listens
-            # on tcp://0.0.0.0:2376 (TLS) which the runner reaches at localhost:2376.
-            - name: DOCKER_TLS_CERTDIR
-              value: /certs
-          volumeMounts:
-            - name: certs
-              mountPath: /certs
-            - name: dind-storage
-              mountPath: /var/lib/docker
-          resources:
-            requests:
-              cpu: 100m
-              memory: 256Mi
-            limits:
-              memory: 2Gi
      volumes:
        - name: data
          persistentVolumeClaim:
@@ -184,26 +184,6 @@ spec:
    - name: keycloak
      port: 8080
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: keycloak
-  namespace: keycloak
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: keycloak
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: keycloak
-  namespaceSelector:
-    matchNames:
-    - keycloak
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -218,11 +198,11 @@ spec:
  - name: keycloak.slis
    rules:
    - alert: keycloak-down
-      expr: up{job="keycloak"} == 0
+      expr: kube_statefulset_status_replicas_ready{namespace="keycloak", statefulset="keycloak"} == 0 or absent(kube_statefulset_status_replicas_ready{namespace="keycloak", statefulset="keycloak"})
      for: 5m
      labels:
        severity: critical
        service: keycloak
      annotations:
        summary: keycloak is down
-        description: 'keycloak has been unreachable for 5m (SLI: up).'
+        description: 'keycloak: its StatefulSet has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_statefulset_status_replicas_ready).'
@@ -290,26 +290,6 @@ spec:
    - name: nextcloud
      port: 80
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: nextcloud
-  namespace: nextcloud
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: nextcloud
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: nextcloud
-  namespaceSelector:
-    matchNames:
-    - nextcloud
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -324,11 +304,11 @@ spec:
  - name: nextcloud.slis
    rules:
    - alert: nextcloud-down
-      expr: up{job="nextcloud"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="nextcloud", deployment="nextcloud"} == 0 or absent(kube_deployment_status_replicas_available{namespace="nextcloud", deployment="nextcloud"})
      for: 5m
      labels:
        severity: critical
        service: nextcloud
      annotations:
        summary: nextcloud is down
-        description: 'nextcloud has been unreachable for 5m (SLI: up).'
+        description: 'nextcloud: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -348,6 +348,7 @@ metadata:
  annotations:
    homelab.keithjackson.dev/auth-mode: forward-auth
    homelab.keithjackson.dev/auth-groups: media-users,platform-admins
+    external-dns.alpha.kubernetes.io/controller: none
 spec:
  parentRefs:
  - name: shared
@@ -364,26 +365,6 @@ spec:
    - name: radarr
      port: 4180
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: radarr
-  namespace: radarr
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: radarr
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: radarr
-  namespaceSelector:
-    matchNames:
-    - radarr
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -398,11 +379,11 @@ spec:
  - name: radarr.slis
    rules:
    - alert: radarr-down
-      expr: up{job="radarr"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="radarr", deployment="radarr"} == 0 or absent(kube_deployment_status_replicas_available{namespace="radarr", deployment="radarr"})
      for: 5m
      labels:
        severity: critical
        service: radarr
      annotations:
        summary: radarr is down
-        description: 'radarr has been unreachable for 5m (SLI: up).'
+        description: 'radarr: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -227,6 +227,7 @@ metadata:
  annotations:
    homelab.keithjackson.dev/auth-mode: oidc
    homelab.keithjackson.dev/auth-groups: platform-admins
+    external-dns.alpha.kubernetes.io/controller: none
 spec:
  parentRefs:
  - name: shared
@@ -243,26 +244,6 @@ spec:
    - name: semaphore
      port: 3000
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: semaphore
-  namespace: semaphore
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: semaphore
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: semaphore
-  namespaceSelector:
-    matchNames:
-    - semaphore
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -277,11 +258,11 @@ spec:
  - name: semaphore.slis
    rules:
    - alert: semaphore-down
-      expr: up{job="semaphore"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="semaphore", deployment="semaphore"} == 0 or absent(kube_deployment_status_replicas_available{namespace="semaphore", deployment="semaphore"})
      for: 5m
      labels:
        severity: critical
        service: semaphore
      annotations:
        summary: semaphore is down
-        description: 'semaphore has been unreachable for 5m (SLI: up).'
+        description: 'semaphore: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -348,6 +348,7 @@ metadata:
  annotations:
    homelab.keithjackson.dev/auth-mode: forward-auth
    homelab.keithjackson.dev/auth-groups: media-users,platform-admins
+    external-dns.alpha.kubernetes.io/controller: none
 spec:
  parentRefs:
  - name: shared
@@ -364,26 +365,6 @@ spec:
    - name: sonarr
      port: 4180
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: sonarr
-  namespace: sonarr
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: sonarr
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: sonarr
-  namespaceSelector:
-    matchNames:
-    - sonarr
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -398,11 +379,11 @@ spec:
  - name: sonarr.slis
    rules:
    - alert: sonarr-down
-      expr: up{job="sonarr"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="sonarr", deployment="sonarr"} == 0 or absent(kube_deployment_status_replicas_available{namespace="sonarr", deployment="sonarr"})
      for: 5m
      labels:
        severity: critical
        service: sonarr
      annotations:
        summary: sonarr is down
-        description: 'sonarr has been unreachable for 5m (SLI: up).'
+        description: 'sonarr: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -0,0 +1,245 @@
+# promtool rule-unit tests for the wave-1 per-app `<app>-down` SLI rules.
+# Manifests under test: every PrometheusRule in apps/wave-1/ — nextcloud, radarr, semaphore, sonarr
+# (container/Deployment) and keycloak (StatefulSet, see below). Discovered by the SUITE convention;
+# the flattened manifests are the RENDERED ones Flux applies.
+#
+# Run with: platform/monitoring/tests/run.sh apps/wave-1/tests/app-slis.test.yaml
+#
+# See apps/wave-0/tests/app-slis.test.yaml for the full history: these rules all read
+# `up{job="<app>"} == 0` until 2026-09-13 against a job no scrape target produced, and were
+# structurally inert on prod. Each is now pinned QUIET on the healthy state, FIRING on no-ready-
+# replica, and FIRING when the signal is ABSENT.
+#
+# KEYCLOAK IS THE INTERESTING ONE. Its server is a StatefulSet run by the Keycloak operator, NOT the
+# Deployment this ServiceDefinition would otherwise imply — so its rule reads
+# kube_statefulset_status_replicas_ready (catalog/keycloak.yaml declares
+# `observability.livenessWorkload: {kind: StatefulSet, name: keycloak}`). Had it been left to the
+# default, the `absent()` half would have matched forever and the alert would have been PERMANENTLY
+# FIRING, which is the other failure mode this repo has shipped to prod. Verified on prod
+# 2026-09-13: kube_statefulset_status_replicas_ready{namespace="keycloak", statefulset="keycloak"}
+# = 2, and the only Deployment in that namespace is keycloak-operator.
+rule_files:
+  - generated.rules.yaml
+
+evaluation_interval: 1m
+
+tests:
+  # ===========================================================================================
+  # 1. HEALTHY WAVE-1 -> every rule SILENT ("not permanently firing").
+  # ===========================================================================================
+  - interval: 1m
+    name: wave-1 healthy - every app ready, keycloak StatefulSet at 2 replicas - all quiet
+    input_series:
+      - series: 'kube_statefulset_status_replicas_ready{namespace="keycloak", statefulset="keycloak"}'
+        values: '2+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="nextcloud", deployment="nextcloud"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="radarr", deployment="radarr"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="semaphore", deployment="semaphore"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="sonarr", deployment="sonarr"}'
+        values: '1+0x20'
+      # The namespace's OTHER workloads are present on purpose: keycloak-operator is a Deployment in
+      # the keycloak namespace, and keycloak-db is a StatefulSet in it. A rule that matched the
+      # namespace only (not the object) would be satisfied — or triggered — by these instead of by
+      # the IdP itself. That is the exact masking KeycloakDown had to be fixed for.
+      - series: 'kube_deployment_status_replicas_available{namespace="keycloak", deployment="keycloak-operator"}'
+        values: '1+0x20'
+      - series: 'kube_statefulset_status_replicas_ready{namespace="keycloak", statefulset="keycloak-db"}'
+        values: '3+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: keycloak-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: nextcloud-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: radarr-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: semaphore-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: sonarr-down
+        exp_alerts: []
+
+  # ===========================================================================================
+  # 2. THE IdP ITSELF IS DOWN while its operator and DB are fine -> ONLY keycloak-down fires.
+  #    This is the anti-masking assertion: the neighbours in that namespace stay ready.
+  # ===========================================================================================
+  - interval: 1m
+    name: wave-1 keycloak StatefulSet has no ready replica (operator + DB fine) - keycloak-down fires
+    input_series:
+      - series: 'kube_statefulset_status_replicas_ready{namespace="keycloak", statefulset="keycloak"}'
+        values: '0+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="keycloak", deployment="keycloak-operator"}'
+        values: '1+0x20'
+      - series: 'kube_statefulset_status_replicas_ready{namespace="keycloak", statefulset="keycloak-db"}'
+        values: '3+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="nextcloud", deployment="nextcloud"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="radarr", deployment="radarr"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="semaphore", deployment="semaphore"}'
+        values: '1+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="sonarr", deployment="sonarr"}'
+        values: '1+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: keycloak-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: keycloak
+              namespace: keycloak
+              statefulset: keycloak
+            exp_annotations:
+              summary: "keycloak is down"
+              description: "keycloak: its StatefulSet has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_statefulset_status_replicas_ready)."
+      - eval_time: 10m
+        alertname: nextcloud-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: radarr-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: semaphore-down
+        exp_alerts: []
+      - eval_time: 10m
+        alertname: sonarr-down
+        exp_alerts: []
+
+  # ===========================================================================================
+  # 3. EACH DEPLOYMENT-BACKED APP DOWN -> its own rule fires, keycloak stays quiet.
+  # ===========================================================================================
+  - interval: 1m
+    name: wave-1 nextcloud/radarr/semaphore/sonarr have no available replica - each own rule fires
+    input_series:
+      - series: 'kube_statefulset_status_replicas_ready{namespace="keycloak", statefulset="keycloak"}'
+        values: '2+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="nextcloud", deployment="nextcloud"}'
+        values: '0+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="radarr", deployment="radarr"}'
+        values: '0+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="semaphore", deployment="semaphore"}'
+        values: '0+0x20'
+      - series: 'kube_deployment_status_replicas_available{namespace="sonarr", deployment="sonarr"}'
+        values: '0+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: nextcloud-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: nextcloud
+              namespace: nextcloud
+              deployment: nextcloud
+            exp_annotations:
+              summary: "nextcloud is down"
+              description: "nextcloud: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: radarr-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: radarr
+              namespace: radarr
+              deployment: radarr
+            exp_annotations:
+              summary: "radarr is down"
+              description: "radarr: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: semaphore-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: semaphore
+              namespace: semaphore
+              deployment: semaphore
+            exp_annotations:
+              summary: "semaphore is down"
+              description: "semaphore: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: sonarr-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: sonarr
+              namespace: sonarr
+              deployment: sonarr
+            exp_annotations:
+              summary: "sonarr is down"
+              description: "sonarr: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: keycloak-down
+        exp_alerts: []
+
+  # ===========================================================================================
+  # 4. THE SIGNAL VANISHES -> the rules FIRE. The defect class itself, asserted on: a rule that can
+  #    only fire on `== 0` goes SILENT when kube-state-metrics or the workload object disappears,
+  #    which is indistinguishable from healthy. Here NOTHING in wave-1 is scraped.
+  # ===========================================================================================
+  - interval: 1m
+    name: wave-1 all liveness series ABSENT (kube-state-metrics gone) - every rule fires
+    input_series:
+      # One unrelated series so the test has an input at all; no wave-1 liveness series exists.
+      - series: 'up{job="kube-state-metrics"}'
+        values: '0+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: keycloak-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: keycloak
+              namespace: keycloak
+              statefulset: keycloak
+            exp_annotations:
+              summary: "keycloak is down"
+              description: "keycloak: its StatefulSet has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_statefulset_status_replicas_ready)."
+      - eval_time: 10m
+        alertname: nextcloud-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: nextcloud
+              namespace: nextcloud
+              deployment: nextcloud
+            exp_annotations:
+              summary: "nextcloud is down"
+              description: "nextcloud: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: radarr-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: radarr
+              namespace: radarr
+              deployment: radarr
+            exp_annotations:
+              summary: "radarr is down"
+              description: "radarr: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: semaphore-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: semaphore
+              namespace: semaphore
+              deployment: semaphore
+            exp_annotations:
+              summary: "semaphore is down"
+              description: "semaphore: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+      - eval_time: 10m
+        alertname: sonarr-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: sonarr
+              namespace: sonarr
+              deployment: sonarr
+            exp_annotations:
+              summary: "sonarr is down"
+              description: "sonarr: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
@@ -233,26 +233,6 @@ spec:
    - name: seerr
      port: 5055
 ---
-# ServiceMonitor (R-OBS-01)
-apiVersion: monitoring.coreos.com/v1
-kind: ServiceMonitor
-metadata:
-  name: seerr
-  namespace: seerr
-  labels:
-    release: kube-prometheus-stack
-    app.kubernetes.io/name: seerr
-spec:
-  selector:
-    matchLabels:
-      app.kubernetes.io/name: seerr
-  namespaceSelector:
-    matchNames:
-    - seerr
-  endpoints:
-  - port: metrics
-    interval: 30s
---
 # PrometheusRule SLI alerts (R-OBS-01)
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
@@ -267,11 +247,11 @@ spec:
  - name: seerr.slis
    rules:
    - alert: seerr-down
-      expr: up{job="seerr"} == 0
+      expr: kube_deployment_status_replicas_available{namespace="seerr", deployment="seerr"} == 0 or absent(kube_deployment_status_replicas_available{namespace="seerr", deployment="seerr"})
      for: 5m
      labels:
        severity: critical
        service: seerr
      annotations:
        summary: seerr is down
-        description: 'seerr has been unreachable for 5m (SLI: up).'
+        description: 'seerr: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available).'
@@ -0,0 +1,69 @@
+# promtool rule-unit tests for the wave-2 per-app `<app>-down` SLI rule (seerr).
+# Manifest under test: apps/wave-2/seerr.yaml. Discovered by the SUITE convention; the flattened
+# manifest is the RENDERED one Flux applies.
+#
+# Run with: platform/monitoring/tests/run.sh apps/wave-2/tests/app-slis.test.yaml
+#
+# seerr (Jellyseerr/Overseerr) exports NO Prometheus metrics of its own, so its `up` SLI could never
+# have been met by scraping the app — see apps/wave-0/tests/app-slis.test.yaml for the full history
+# of the inert `up{job="seerr"} == 0` rule this replaces. Pinned in both directions plus the
+# signal-vanishes case.
+rule_files:
+  - generated.rules.yaml
+
+evaluation_interval: 1m
+
+tests:
+  - interval: 1m
+    name: wave-2 healthy - seerr has an available replica - quiet
+    input_series:
+      - series: 'kube_deployment_status_replicas_available{namespace="seerr", deployment="seerr"}'
+        values: '1+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: seerr-down
+        exp_alerts: []
+
+  - interval: 1m
+    name: wave-2 seerr has no available replica - seerr-down fires
+    input_series:
+      - series: 'kube_deployment_status_replicas_available{namespace="seerr", deployment="seerr"}'
+        values: '0+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: seerr-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: seerr
+              namespace: seerr
+              deployment: seerr
+            exp_annotations:
+              summary: "seerr is down"
+              description: "seerr: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
+    # Under `for: 5m` a 2m-old condition must NOT yet be a firing alert, but the expression must
+    # already be selecting — the distinction an inert rule cannot make.
+    promql_expr_test:
+      - expr: 'kube_deployment_status_replicas_available{namespace="seerr", deployment="seerr"} == 0 or absent(kube_deployment_status_replicas_available{namespace="seerr", deployment="seerr"})'
+        eval_time: 2m
+        exp_samples:
+          - labels: 'kube_deployment_status_replicas_available{deployment="seerr", namespace="seerr"}'
+            value: 0
+
+  - interval: 1m
+    name: wave-2 seerr liveness series ABSENT - seerr-down still fires
+    input_series:
+      - series: 'up{job="kube-state-metrics"}'
+        values: '1+0x20'
+    alert_rule_test:
+      - eval_time: 10m
+        alertname: seerr-down
+        exp_alerts:
+          - exp_labels:
+              severity: critical
+              service: seerr
+              namespace: seerr
+              deployment: seerr
+            exp_annotations:
+              summary: "seerr is down"
+              description: "seerr: its Deployment has no available/ready replica for 5m, or the signal is gone entirely (SLI: up, via kube_deployment_status_replicas_available)."
@@ -180,6 +180,34 @@ dependencies: []                # default-deny: reaches only DNS; git clients re
 ingressRoutes:
  - host: gitea.${BASE_DOMAIN}
    port: 3000                  # Gitea HTTP web/API; TLS terminates at the shared Gateway (docs/08, docs/09)
+# THIS IS WHAT KEEPS PROD'S GITOPS OUT OF A DEADLOCK — it is not an incidental allowance. Remove it
+# and prod cannot reconcile AT ALL, in a way that is very hard to diagnose from cold.
+#
+# Prod's Flux source is THIS SERVICE, not a public hostname:
+#   clusters/prod/kustomization.yaml -> GitRepository.spec.url =
+#   http://gitea.gitea.svc.cluster.local:3000/Home-Network/home-network-k3s-impl.git
+# chosen deliberately so prod's GitOps depends on NEITHER public DNS, Cloudflare, prod's own
+# Gateway, NOR ${BASE_DOMAIN} — a future domain change cannot sever prod from its own source. That
+# file documents the other half of this pair at length; the two must be read together.
+#
+# The only other ingress this entry renders is gitea-allow-gateway-ingress, which admits
+# `fromEntities: [ingress]` — the shared Gateway's Envoy proxy — and nothing else. Flux's
+# source-controller dials the ClusterIP DIRECTLY, so under the namespace default-deny (R-NET-01) its
+# clone was DROPPED (`wget` from source-controller timed out; srcReady=False, "unable to list
+# remote"). The deadlock that made this urgent: the HTTPRoute that would have served the new public
+# name after the 2026-09-13 apex flip lives in a DOWNSTREAM tier, which cannot apply while the
+# source is down — source down -> routes never rename -> source stays down. It was broken on
+# 2026-09-13 with a live `kubectl apply` of a hand-written gitea-allow-flux-ingress, i.e. with a
+# cluster object that existed OUTSIDE git. This declaration renders that object, so one
+# `kubectl delete` or one cluster rebuild can no longer put prod back in the deadlock.
+inClusterClients:
+  # `name` is pinned to `flux` (rather than defaulting to the namespace) so the rendered policy name
+  # equals the live object's, `gitea-allow-flux-ingress`, and Flux ADOPTS it in place: no
+  # near-duplicate policy beside it, and no window in which prod's own source has no allow.
+  - name: flux
+    namespace: flux-system      # matched by NAMESPACE alone — the flux controllers' pod labels belong
+                                # to upstream's manifests, not to this platform's contract
+    port: 3000                  # ONLY the Gitea HTTP port — the same single port the Gateway allow opens
 auth:
  mode: oidc                    # native Keycloak OIDC client (docs/13 SSO row, docs/15 "Native OIDC" set; R-IDP-02)
  groups:
@@ -31,5 +31,15 @@ observability:
  metrics: true
  slis:
    - up                      # IdP down/unhealthy is a critical alert (docs/10; R-OBS-01)
+  # WHAT "up" IS for Keycloak. The Keycloak OPERATOR runs the server as a StatefulSet named
+  # `keycloak` (pods keycloak-0/1), not as the Deployment this ServiceDefinition would otherwise
+  # imply — the operator owns the workload (platform/keycloak/keycloak-instance.yaml) and this SD
+  # is the catalog's declaration of intent for it. Without this override the rendered SLI would
+  # read a Deployment series that does not exist and its `absent()` half would fire FOREVER.
+  # Verified on prod 2026-09-13: kube_statefulset_status_replicas_ready{namespace="keycloak",
+  # statefulset="keycloak"} = 2, and the only Deployment in that namespace is keycloak-operator.
+  livenessWorkload:
+    kind: StatefulSet
+    name: keycloak
 backup:
  policy: daily-offcluster    # DR-critical: rebuilds from DB + git realm config (docs/15, docs/04; R-STATE-03)
@@ -13,6 +13,93 @@ storage:
    size: 2Gi
    class: longhorn           # replicated config state; DR-critical (docs/04 line 118; R-STATE-02/03)
 dependencies: []              # default-deny: reaches only DNS; it PROVIDES DNS (docs/03; R-NET-01/02)
+# ------------------------------------------------------------------------------------------------
+# LAN SPLIT-HORIZON DNS — the half of R-DNS-03 that platform/coredns/coredns-custom.yaml defers to.
+# ------------------------------------------------------------------------------------------------
+# coredns-custom answers the ${BASE_DOMAIN} zone for PODS ONLY and says so in its own header ("LAN
+# clients keep their own answers (PiHole split-horizon)"). Until now PiHole served no DNS at all —
+# its Service was ClusterIP :80/:4180, no port 53, no LoadBalancer — so the LAN half did not exist
+# and LAN clients depended on hand-maintained per-client dnsmasq files. One went stale after the dev
+# decommission and cost the operator sonarr.${BASE_DOMAIN}. Upstream cannot cover for it either: the
+# SOHO router that owns this LAN strips RFC1918 answers for public domains as rebind protection and
+# returns NOERROR / ANSWER 0. apps/wave-0/pihole-dns.yaml exposes udp/53 + tcp/53 on
+# ${PIHOLE_DNS_VIP}; these env vars are what make the ANSWERS declarative.
+#
+# WHY env AND NOT A RECONCILER: the repo's level-triggered CronJob reconcilers
+# (platform/keycloak/client-secret-reconciler.yaml, the CNPG grant reconciler in
+# apps/wave-0/nextcloud-db.yaml) exist because their state has NO declarative entry point — a
+# Keycloak client secret lives in Keycloak's own database and a Postgres GRANT lives in the
+# catalog, and nothing in a manifest can express either. PiHole v6 is not that case. Every FTL
+# setting has an `FTLCONF_<section>_<key>` environment variable, and a value supplied that way is
+# ENV-FORCED: FTL logs it as "forced through environment", applies it on every start ahead of
+# /etc/pihole/pihole.toml, and marks it read-only in the admin UI so a human cannot drift it. That
+# is strictly better than a reconciler — it is enforced at t=0 on a cold start rather than at the
+# next cron tick, it cannot be defeated by the UI, and it carries no extra RBAC, image or Job. A
+# CronJob here would be ceremony around a knob the app already exposes. (Verified on the live prod
+# image, PiHole Core v6.4.3 / FTL v6.7, 2026-09-14.)
+#
+# THE PVC IS NOT THE MECHANISM AND MUST NOT BE. The `config` volume below mounts at /data/config;
+# PiHole's actual state directory is /etc/pihole, which is EPHEMERAL in this Deployment. Anything
+# configured through the UI is lost on the next reschedule — which is exactly what happened to the
+# upstream servers: the live pod's pihole.toml carried a hand-set `upstreams` marked "### CHANGED"
+# that no manifest declared, so a restart would have left PiHole with upstreams = [] and no
+# recursion at all. Declaring upstreams here closes that too: PiHole must stay a usable GENERAL
+# resolver, not only authoritative for this zone, or pointing LAN clients at it breaks the internet.
+env:
+  # Default is LOCAL, which answers only clients on the same subnet as the listening interface. The
+  # pod's interface is on the CLUSTER pod CIDR, so every LAN client would be refused. ALL is
+  # required for a LoadBalancer-fronted resolver; what keeps PiHole from being an OPEN resolver is
+  # the exposure, not this setting — `loadBalancerSourceRanges: [${LAN_CIDR}]` on the DNS Services,
+  # enforced by Cilium in the datapath before load-balancing, plus a CiliumNetworkPolicy that admits
+  # nothing but udp/53 and tcp/53. See apps/wave-0/pihole-dns.yaml.
+  - name: FTLCONF_dns_listeningMode
+    value: "ALL"
+  # Recursion for everything that is NOT this zone. Public resolvers on purpose, NOT the SOHO
+  # router at the LAN gateway: that router is the box whose rebind protection strips RFC1918
+  # answers, and forwarding to a device that may forward back here invites a loop.
+  - name: FTLCONF_dns_upstreams
+    value: "8.8.8.8;8.8.4.4"
+  # Per-client query rate limit OFF (default: 1000 queries per 60s, then REFUSED). It has to be off
+  # because of how the DNS Services are exposed: apps/wave-0/pihole-dns.yaml uses
+  # externalTrafficPolicy Cluster — it must, or LAN resolution breaks whenever Cilium's L2
+  # announcement lease and the pihole pod land on different nodes, which is most of the time — and
+  # Cilium runs in SNAT mode here, so a query forwarded between nodes reaches PiHole carrying the
+  # INGRESS NODE's address instead of the client's. Every LAN device therefore counts against ONE
+  # apparent client's budget, and a normal evening of browsing from a handful of machines would trip
+  # a limit meant to catch one misbehaving host. Leaving it at the default turns the whole LAN's DNS
+  # off for 60 seconds at a time, intermittently, which is the worst possible failure shape. The
+  # limit becomes meaningful again — and should be restored — if Cilium is ever switched to
+  # `loadBalancer.mode: dsr`, which preserves the client address.
+  - name: FTLCONF_dns_rateLimit_count
+    value: "0"
+  # THE SPLIT-HORIZON ANSWERS. A dnsmasq `address=/<domain>/<ip>` entry answers that domain AND
+  # every subdomain of it, and dnsmasq resolves overlapping entries by LONGEST MATCHING DOMAIN —
+  # so the first line is a wildcard for the whole zone and each later line is a specific override.
+  # PRECEDENCE IS THEREFORE STRUCTURAL, not order-dependent: `unifi.${BASE_DOMAIN}` matches both
+  # line 1 and line 2, line 2 is the longer domain, line 2 wins. Rewriting these in any order
+  # changes nothing.
+  #
+  # A NEWLY ONBOARDED SERVICE NEEDS NO CHANGE HERE. Every catalog ingressRoute host is
+  # `<label>.${BASE_DOMAIN}` served by the shared Gateway, so the wildcard already answers it with
+  # ${GATEWAY_VIP} — the same guarantee, and the same reasoning, as the `template IN A` block in
+  # platform/coredns/coredns-custom.yaml. Add a line here ONLY for a service that does not live
+  # behind the Gateway: an L4 LoadBalancer on its own pinned VIP. Those are enumerated from the
+  # repo, not from memory — grep `external-dns.alpha.kubernetes.io/hostname` on a Service, which
+  # is the annotation that means "this Service publishes its own hostname at its own address":
+  # apps/vms/unifi/50-service-l4.yaml (unifi -> ${UNIFI_L4_VIP}) and
+  # platform/crafty/service-l4.yaml (crafty-mc -> ${CRAFTY_L4_VIP}). Those two, plus PiHole's own
+  # resolver address, are the complete set of exceptions today.
+  #
+  # AAAA needs nothing: dnsmasq answers a AAAA query for an `address=`d name with NODATA
+  # (NOERROR, no answer), so IPv6-capable clients fall back to the A record instead of getting
+  # NXDOMAIN — the same behaviour coredns-custom hand-writes a `template IN AAAA` block for.
+  #
+  # Array-valued FTLCONF variables are SEMICOLON-separated. A JSON-looking list is accepted and
+  # then silently wrong: FTL stores `["a","b"]` as ONE array element containing those literal
+  # characters, writes that single bogus line into /etc/pihole/dnsmasq.conf and reports "0 invalid"
+  # while resolution for the zone does not work. Confirmed both ways against the live image.
+  - name: FTLCONF_misc_dnsmasq_lines
+    value: "address=/${BASE_DOMAIN}/${GATEWAY_VIP};address=/unifi.${BASE_DOMAIN}/${UNIFI_L4_VIP};address=/crafty-mc.${BASE_DOMAIN}/${CRAFTY_L4_VIP};address=/pihole-dns.${BASE_DOMAIN}/${PIHOLE_DNS_VIP}"
 ingressRoutes:
  - host: pihole.${BASE_DOMAIN}
    port: 80                  # admin web UI, protected at the Gateway by forward-auth (docs/09)
@@ -32,11 +32,46 @@ env:
  # (10.43.0.0/16); 192.168.0.0/16 covers the home LAN.
  - name: ALLOWED_NETWORKS
    value: 10.0.0.0/8,192.168.0.0/16
-  # PLEX_CLAIM is deliberately NOT set here: a https://plex.tv/claim token has a ~4-min TTL, far
-  # shorter than the commit -> push -> Flux reconcile -> pod-roll cycle, so any token committed to git
-  # is already expired by the time the pod starts. Claiming is a one-time LIVE step (UI sign-in, or a
-  # single API POST) against the running server; the claim then persists on the /config PVC and
-  # survives pod rolls (including the roll this env change causes), so it never belongs in git.
+  # PLEX_CLAIM — the ONE-SHOT plex.tv server claim, sourced from the SOPS Secret `plex-claim`
+  # (apps/wave-0/plex-claim-secret.sops.yaml, same wave => applied in the same reconcile as this
+  # workload). Plex cannot create libraries over the mounted bulk share while the server is
+  # UNCLAIMED, so this is wired; it was previously left out on the reasoning below, and only one
+  # half of that reasoning survived contact with the upstream source.
+  #
+  # A SHORT TTL IS THE OPERATIONAL CONSTRAINT, not a reason to abstain. A https://plex.tv/claim token
+  # expires in MINUTES — read the countdown the claim page renders; do not budget against a number
+  # written in this tree. (This comment previously asserted "~4 minutes" as established fact. It was
+  # UNCITED, upstream plexinc/pms-docker documents no expiry at all, and that number was load-bearing
+  # for the whole procedure design — including a since-disproven claim that the delivery pipeline was
+  # too slow to fit inside it. Measured 2026-09-29: the full loop is ~2m45s and fits.)
+  #
+  # The live token is injected by the operator inside that window, with an explicit `flux reconcile`
+  # to collapse the wait. Scripted end to end as infra/plex/claim-ship.sh; runbooks/plex-claim.md is
+  # the procedure. SERVER CLAIMED 2026-09-29 — this env is now a permanent no-op (see below), and the
+  # committed value is the spent token from that claim rather than the original placeholder.
+  #
+  # ONE-SHOT, AND SAFE TO SIT HERE EXPIRED. Verified from plexinc/pms-docker's own first-run script
+  # (branch `master`, root/etc/cont-init.d/40-plex-first-run, confirmed byte-identical to the file in
+  # the running `:latest` image), NOT assumed:
+  #   - the exchange (line 106) is guarded on TWO conditions: PLEX_CLAIM non-empty AND the
+  #     PlexOnlineToken pref in /config empty. Once claimed, the block is SKIPPED — this env is a
+  #     no-op on every subsequent start, whatever it holds. (Upstream README: "If server is already
+  #     logged in, this parameter is ignored.") The claim itself persists on the /config PVC as before.
+  #   - an invalid/expired token on a still-unclaimed /config gets a 403 with an empty body; curl's
+  #     status is unchecked, the token `sed` yields "", the success branch at line 120 does not fire,
+  #     there is no `else` and no `exit 1`, and the script (no `set -e`) exits 0. It comes up UNCLAIMED and
+  #     SERVING — it does NOT crashloop. The image also leaves S6_BEHAVIOUR_IF_STAGE2_FAILS at its
+  #     default 0, which continues startup even when a cont-init script fails.
+  # So the earlier "a placeholder claim Secret would crashloop the pod" note was WRONG about the
+  # placeholder; it was right only about an ABSENT Secret. secretKeyRef here has no `optional` field,
+  # so the Secret must always exist in the Flux graph — which is why it is committed, encrypted, and
+  # listed in apps/wave-0/kustomization.yaml rather than hand-created at claim time. No schema change
+  # is needed: `optional` would only matter if a missing Secret had to be tolerated, and it doesn't.
+  - name: PLEX_CLAIM
+    valueFrom:
+      secretKeyRef:
+        name: plex-claim
+        key: PLEX_CLAIM
  # ADVERTISE_IP ("Custom server access URLs") is DEFERRED, not accidentally omitted. It tells Plex
  # which URL to advertise to plex.tv for REMOTE clients. The only candidate is
  # https://plex.home.keithjackson.dev, but that host resolves via split-horizon DNS to the INTERNAL
@@ -56,10 +91,12 @@ storage:
                              # container's EPHEMERAL layer -> unclaimed + all state lost on restart. The image inits as
                              # root (s6-svscan PID 1), chowns /config to the plex user, then drops -> no fsGroup needed
                              # (verified in-cluster: PID1=root, "Plex Media Server"=plex). Persisting /config here also
-                              # makes the claim survive restarts once claimed. To auto-claim on first boot instead of the
-                              # UI sign-in, the operator adds a PLEX_CLAIM env from a fresh https://plex.tv/claim token
-                              # (4-min TTL) — deliberately NOT wired here: the env secretKeyRef pattern has no `optional`,
-                              # so a placeholder/absent claim Secret would crashloop the pod. See operator hand-off.
+                              # makes the claim survive restarts once claimed — which is what makes the PLEX_CLAIM env
+                              # above a ONE-SHOT: the token is exchanged for a PlexOnlineToken written here, and the
+                              # exchange is then skipped on every later start. (The older note here claimed a
+                              # placeholder claim Secret "would crashloop the pod"; upstream's first-run script says
+                              # otherwise — see the PLEX_CLAIM comment in `env` above. An ABSENT Secret is the hard
+                              # failure, and that is why one is committed.)
  # THE LIBRARY (docs/04 bulk tier). One READ-ONLY mount of the export ROOT, giving /media/movies,
  # /media/tv and /media/photos — the whole tree the layout actually has (`ls /mnt/Storage/plex`:
  # downloads/ movies/ photos/ tv/).
@@ -4,19 +4,18 @@
 # internal download client | egress VPN + kill-switch | config on Longhorn | auth forward-auth
 # (bare web UI, no native OIDC).
 #
-# BULK DOWNLOADS TIER — OPEN PREREQUISITE, intentionally NOT declared here (mirrors plex + sonarr/radarr):
-#   docs/13 row 13 places qBittorrent's downloads/staging volume on the `bulk` tier (large, non-3x-
-#   replicated media handoff to the arr stack). The `bulk` StorageClass exists
-#   (platform/longhorn/storageclasses.yaml) and both the schema and renderer support `class: bulk`, BUT
-#   it is a NON-PROVISIONING STUB pending OQ-2 (its NFS/SMB backing is REPLACE-ME and the NFS CSI driver
-#   is not installed) — a `bulk` PVC would never bind and would leave the pod Pending. Declaring it now
-#   would also pull the bulk-tier requirement into the change's "touched" set, whose in-cluster
-#   conformance test is not yet scaffolded, blocking the merge gate. So the downloads volume is DEFERRED
-#   and this onboarding ships config-only. Once OQ-2 is resolved and `bulk` provisions, attach downloads
-#   with a one-line add under storage:
-#         - name: downloads
-#           class: bulk          # external mount; size omitted (sized outside the cluster)
-#   then re-render. See the WS-APPS report for the full bulk-downloads finding.
+# BULK DOWNLOADS TIER — DELIVERED 2026-09-12 (the deferral below is CLOSED; kept for the record).
+#   This entry used to ship config-only, with a comment promising to attach the downloads volume "once
+#   OQ-2 is resolved". OQ-2 was resolved for STATIC pre-existing datasets (schema 1.5.0 / renderer
+#   `class: bulk` + `export` -> a static, pre-bound NFS PV), and plex/sonarr/radarr/nextcloud all took
+#   their media mounts — but qBittorrent's was never added, so the DOWNLOAD CLIENT was the one member
+#   of the chain with no media volume at all. Measured on prod 2026-09-12:
+#       Session\DefaultSavePath=/downloads/   Session\TempPath=/downloads/incomplete/
+#       Downloads\SavePath=/downloads/       `ls /downloads` -> No such file or directory
+#   i.e. the app was configured to write a path that DID NOT EXIST, in a container with no volume there.
+#   Anything it did manage to create would have been invisible to sonarr/radarr, lost on every pod
+#   recreation, and filling the NODE's ephemeral disk in the meantime. The `downloads` entry under
+#   storage: below closes that. See docs/BULK-NFS-STORAGE.md and the bulk-tier L0 conformance test.
 #
 # VPN-class (docs/13 row 13; docs/03 "VPN-class set"): ALL of this pod's public-internet egress
 # (peer/tracker/DHT traffic) MUST leave via the node PIA tunnel, never the WAN. `egress: vpn` renders
@@ -32,6 +31,316 @@ name: qbittorrent
 kind: container
 source:
  image: lscr.io/linuxserver/qbittorrent:5.1.2   # pinned stable tag (R-UPD-01); update.range governs advancement
+# LinuxServer images run their service as the user `abc`, whose uid/gid these two set. They are
+# LOAD-BEARING FOR THE BULK MOUNT, not cosmetic — exactly as on sonarr/radarr. Measured on prod
+# 2026-09-12 BEFORE this change: `id` inside the container reported the qbittorrent-nox process as
+# uid=911 gid=911, and /mnt/Storage/plex/downloads is 0755 owned 1000:1000. 0755 grants write to the
+# OWNER ONLY, so uid 911 would have mounted the export cleanly and then failed every write with
+# EACCES — the "mounts fine, cannot write" failure the sonarr entry warns about at length.
+env:
+  - name: PUID
+    value: "1000"               # owner uid of /mnt/Storage/plex/downloads (and of every dir under the export)
+  - name: PGID
+    value: "3000"               # the export's dominant group, matching sonarr/radarr: files this writes stay
+                                # readable to the EXISTING non-k3s consumers of the same dataset, and land
+                                # group-owned the same way the arrs' own writes do
+  # --- THE DURABLE WebUI CREDENTIAL (consumed by the postStart hook below) -------------------
+  # Measured on prod 2026-09-13: /config/qBittorrent/qBittorrent.conf held NEITHER `WebUI\Username`
+  # NOR `WebUI\Password_PBKDF2`. qBittorrent 5.x reads that as "no credential configured" and mints a
+  # NEW random `admin` password on EVERY process start, announcing it ONLY on stdout ("A temporary
+  # password is provided for this session: ..."). Two real consequences, not hypotheticals:
+  #   * Sonarr and Radarr store a download-client username/password in their OWN databases. Both
+  #     tested valid against the then-current temporary password; both would have started failing at
+  #     the NEXT qbittorrent pod restart, silently breaking Completed Download Handling (the arrs
+  #     report a failed client, not a failed import).
+  #   * The human operator had no stable login: every restart meant reading the pod log.
+  # Provided as apps/wave-0/qbittorrent-bootstrap-secret.sops.yaml (SOPS/age, decrypted by Flux) —
+  # same shape and naming as gitea-bootstrap, so `render.py --emit-waves` places it in this wave.
+  - name: QBT_WEBUI_USERNAME
+    valueFrom:
+      secretKeyRef:
+        name: qbittorrent-bootstrap
+        key: webui-username
+  - name: QBT_WEBUI_PASSWORD
+    valueFrom:
+      secretKeyRef:
+        name: qbittorrent-bootstrap
+        key: webui-password
+lifecycle:
+  # LEVEL-TRIGGERED CREDENTIAL ASSERTION, run on EVERY container start.
+  #
+  # WHY A postStart HOOK AND NOT A CronJob RECONCILER: the repo's idiom for "state Flux cannot reach
+  # directly" is the level-triggered CronJob (platform/keycloak/client-secret-reconciler.yaml,
+  # apps/wave-0/nextcloud-db.yaml). That idiom's PRINCIPLE — desired state lives in git and is
+  # RE-ASSERTED unconditionally, never set once — is exactly what is applied here, but the trigger is
+  # the container start rather than a clock, because the failure this closes IS a container start:
+  #   * The credential is read by qbittorrent-nox ONCE, at process start, from a file on the config
+  #     PVC. A 15-minute cron would therefore leave a 0-15 minute window after every restart, PVC
+  #     restore or rebuild in which the app serves a random password and both arrs are broken. The
+  #     hook has no such window: it runs before/with the very start that would otherwise regenerate.
+  #   * A CronJob would also have to reach the conf from OUTSIDE the pod — mounting an RWO Longhorn
+  #     PVC that the app already holds, or `kubectl exec`-ing with RBAC it would need granting — and
+  #     then edit a file UNDER the running process, whose own save-on-exit can overwrite the edit.
+  #     In-container, before the service starts, none of that exists.
+  #   * It needs no ServiceAccount, no RBAC, no NetworkPolicy and no API token: strictly less
+  #     privilege than the CronJob alternative (R-SEC/least-privilege).
+  # The gitea entry's postStart is the same pattern (idempotent bootstrap of a credential the app
+  # keeps in its own state), and the schema documents this hook for exactly that use.
+  #
+  # AND WHY NOT AN initContainer, which is the genuinely tempting third option: it would run strictly
+  # BEFORE qbittorrent-nox, removing the race the `s6-svc -r` below exists to cover, and its stdout
+  # would reach `kubectl logs -c <init>` instead of the kubelet. Two reasons it loses here:
+  #   * It CANNOT do step (3) — the ground-truth login that proves the WebUI actually accepts the
+  #     credential — because the WebUI is not running yet. That assertion is the most valuable line
+  #     in this whole mechanism: it is what turns "we wrote a file" into "the credential works", and
+  #     writing the right PBKDF2 bytes is precisely the part that is easy to get subtly wrong.
+  #   * The ServiceDefinition schema (1.5.0) has `lifecycle` but NO initContainers field, so it would
+  #     mean a schema version bump plus a renderer change — a blast radius across every service's
+  #     golden — to buy something strictly weaker than what the hook already does.
+  # The honest summary: postStart trades a short, self-healing start-up race (detected and closed by
+  # the s6 restart + re-verify loop) for the ability to VERIFY. That is the right trade.
+  #
+  # DURABILITY, the whole point — all three paths end with the SAME credential:
+  #   pod restart      -> conf on the PVC already holds it; the hook verifies and writes NOTHING.
+  #   config-PVC restore from an older backup -> restore requires the pod to be recreated, so the
+  #                       hook runs and re-asserts over whatever the snapshot contained.
+  #   rebuild from git -> empty PVC; the image copies /defaults/qBittorrent.conf, the hook writes the
+  #                       credential into it before the service is serving. Nothing outside git.
+  #
+  # WHAT IT DOES NOT DO: it never weakens authentication. `WebUI\AuthSubnetWhitelist` (bypassing auth
+  # for the pod CIDR) was REJECTED: it leaves the human login broken, and makes qBittorrent's auth
+  # depend on network policy staying correct forever. The WebUI keeps demanding a password; that
+  # password is simply now known, fixed, and reproducible from git.
+  postStart:
+    exec:
+      command:
+        - /bin/bash
+        - -c
+        - |
+          # Assert the durable WebUI credential in the config PVC's qBittorrent.conf, then PROVE the
+          # running WebUI accepts it. Idempotent: the steady-state path writes nothing at all.
+          #
+          # THIS SCRIPT CONTAINS NO BRACED DOLLAR EXPANSION AT ALL, AND THAT IS DELIBERATE.
+          # apps-wave-0 declares postBuild.substituteFrom cluster-vars, so Flux runs envsubst over
+          # this whole manifest at RECONCILE time. The repo's escape contract (double the dollar;
+          # enforced by render.py's assert_substitution_safe) makes such a form correct ON THE
+          # CLUSTER — but only there:
+          # envsubst collapses the doubled dollar, so the SAME text run any other way (a `kubectl
+          # apply` of the golden, which runs no envsubst; a hand `kubectl exec` of the script during
+          # development) keeps the doubled dollar, which bash reads as its own PID. Not hypothetical;
+          # see the PORT comment below for the bug it actually caused here. Bare `$VAR` and `$(cmd)`
+          # are untouched by envsubst, so they are used throughout and the script behaves IDENTICALLY
+          # however it is run.
+          set -u
+          CONF=/config/qBittorrent/qBittorrent.conf
+          SVC=/run/service/svc-qbittorrent
+          # The WebUI's listening port, as a LITERAL. It matches ingressRoutes[0].port in this
+          # ServiceDefinition — which is the single place the renderer takes the containerPort, the
+          # Service port and the HTTPRoute backend port from — and the image exposes no WEBUI_PORT
+          # env var for a lookup to read anyway.
+          # It USED to be a doubled-dollar default-operator expansion of a WEBUI_PORT env var, and
+          # that cost real time: run without envsubst, bash read the doubled dollar as its own PID,
+          # so PORT became "<pid>{WEBUI_PORT:-8080}" — the brace never expanded, the digits never
+          # matched. Every curl below then got an unparseable URL, returned nothing, and the hook
+          # logged "the WebUI rejected the durable
+          # credential" — having never actually asked it. That MISDIAGNOSIS is preserved in this
+          # service's own marker log at 2026-09-13T05:35Z (three "rejected" lines, then GAVE UP,
+          # against a WebUI that accepted the credential perfectly well). A literal cannot be mangled.
+          PORT=8080
+          # A postStart hook's stdout/stderr goes to the KUBELET, not to `kubectl logs` — so a hook
+          # that only echoes is effectively silent (gitea's hits the same wall and writes a marker
+          # file for it). Every outcome therefore also lands, timestamped, on the persistent config
+          # volume: /config/qbittorrent-webui-cred.log is where an operator looks to see whether the
+          # credential from git was asserted and accepted on this start.
+          log() {
+            echo "[qbt-webui-cred] $*"
+            printf '%s [qbt-webui-cred] %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*" \
+              >> /config/qbittorrent-webui-cred.log 2>/dev/null || true
+          }
+
+          # (1) The image's init-qbittorrent-config copies /defaults/qBittorrent.conf onto the PVC
+          #     before it starts the service. Wait (bounded, ~30s) so we EDIT that file instead of
+          #     racing to create one it would then not overwrite.
+          n=0
+          while [ ! -s "$CONF" ] && [ "$n" -lt 120 ]; do n=$((n + 1)); sleep 0.25; done
+
+          waited=0
+          attempt=0
+          while [ "$attempt" -lt 3 ]; do
+            attempt=$((attempt + 1))
+
+            # (2) Converge the conf. 0 = already correct (steady state: NO write, NO re-salt),
+            #     10 = rewritten, anything else = could not write.
+            python3 - "$CONF" <<'PY'
+          import base64, hashlib, hmac, os, stat, sys
+
+          conf = sys.argv[1]
+          user = os.environ.get("QBT_WEBUI_USERNAME", "")
+          pw = os.environ.get("QBT_WEBUI_PASSWORD", "")
+          if not user or not pw:
+              sys.stderr.write("[qbt-webui-cred] credential env is empty - refusing to touch the conf\n")
+              raise SystemExit(1)
+
+          # qBittorrent's OWN parameters (base/utils/password.cpp): PBKDF2-HMAC-SHA512, 100000
+          # iterations, 16-byte random salt, 64-byte digest, stored as
+          #   WebUI\Password_PBKDF2="@ByteArray(<base64 salt>:<base64 digest>)"
+          # Get any one of them wrong and the app simply rejects every login.
+          ITERATIONS, DIGEST_LEN, SALT_LEN = 100000, 64, 16
+          UKEY, PKEY, SECTION = "WebUI\\Username", "WebUI\\Password_PBKDF2", "[Preferences]"
+
+          def matches(raw):
+              """True iff the stored digest is one OUR password produces (salt is read from it)."""
+              v = raw.strip().strip('"')
+              if v.startswith("@ByteArray(") and v.endswith(")"):
+                  v = v[len("@ByteArray("):-1]
+              try:
+                  salt_b64, digest_b64 = v.split(":", 1)
+                  salt = base64.b64decode(salt_b64, validate=True)
+                  digest = base64.b64decode(digest_b64, validate=True)
+              except Exception:
+                  return False
+              if not salt or not digest:
+                  return False
+              return hmac.compare_digest(
+                  hashlib.pbkdf2_hmac("sha512", pw.encode(), salt, ITERATIONS, len(digest)), digest)
+
+          try:
+              lines = open(conf, encoding="utf-8", errors="replace").read().splitlines()
+          except FileNotFoundError:
+              lines = []
+
+          def value_of(key):
+              for i, line in enumerate(lines):
+                  if line.startswith(key + "="):
+                      return i, line.split("=", 1)[1]
+              return -1, None
+
+          ui, uval = value_of(UKEY)
+          pi, pval = value_of(PKEY)
+          if uval == user and pval is not None and matches(pval):
+              raise SystemExit(0)          # converged - leave the file (and its salt) alone
+
+          salt = os.urandom(SALT_LEN)
+          digest = hashlib.pbkdf2_hmac("sha512", pw.encode(), salt, ITERATIONS, DIGEST_LEN)
+          stored = base64.b64encode(salt).decode() + ":" + base64.b64encode(digest).decode()
+          desired = [UKEY + "=" + user, PKEY + '="@ByteArray(' + stored + ')"']
+
+          out = [line for i, line in enumerate(lines) if i not in (ui, pi)]
+          if SECTION in out:
+              at = out.index(SECTION) + 1
+          else:
+              if out and out[-1].strip():
+                  out.append("")
+              out.append(SECTION)
+              at = len(out)
+          out[at:at] = desired
+
+          try:
+              os.makedirs(os.path.dirname(conf) or ".", exist_ok=True)
+              tmp = conf + ".webui-cred.new"
+              with open(tmp, "w", encoding="utf-8") as fh:
+                  fh.write("\n".join(out) + "\n")
+                  fh.flush()
+                  os.fsync(fh.fileno())
+              # This hook runs as ROOT; the service runs as PUID:PGID. A root-owned 0600 conf would
+              # cost the app the ability to save its own settings, so carry the ownership over.
+              try:
+                  st = os.stat(conf)
+                  os.chown(tmp, st.st_uid, st.st_gid)
+                  os.chmod(tmp, stat.S_IMODE(st.st_mode))
+              except FileNotFoundError:
+                  os.chown(tmp, int(os.environ.get("PUID", "1000")),
+                           int(os.environ.get("PGID", "1000")))
+                  os.chmod(tmp, 0o664)
+              os.replace(tmp, conf)        # atomic: the app never reads a half-written conf
+          except OSError as exc:
+              sys.stderr.write("[qbt-webui-cred] cannot write %s: %s\n" % (conf, exc))
+              raise SystemExit(1)
+          raise SystemExit(10)
+          PY
+            rc=$?
+
+            if [ "$rc" = 0 ]; then
+              log "conf already holds the durable credential for '$QBT_WEBUI_USERNAME' (no write)"
+            elif [ "$rc" = 10 ]; then
+              log "asserted WebUI Username + Password_PBKDF2 into $CONF"
+              # postStart runs CONCURRENTLY with the s6 init chain, so qbittorrent-nox may ALREADY
+              # have read the old, credential-less conf and be serving a random temporary password.
+              # Restart the SUPERVISED SERVICE (not the pod) so it re-reads what was just written.
+              # Nothing to do when the service has not started yet - it will read the new file.
+              # Its own counter, NOT the shared `waited` API budget: sharing one counter is how the
+              # 2026-09-13 failure spent the entire verification budget before the first login and
+              # then fired attempts 2 and 3 with no wait left at all.
+              sv=0
+              while [ "$sv" -lt 60 ] && [ "$(s6-svstat -u "$SVC" 2>/dev/null)" != "true" ]; do
+                sv=$((sv + 1)); sleep 1
+              done
+              if [ "$(s6-svstat -u "$SVC" 2>/dev/null)" = "true" ]; then
+                log "qbittorrent-nox was already running - restarting it to load the credential"
+                s6-svc -r "$SVC" || log "s6-svc -r failed (continuing to verify anyway)"
+                sleep 3
+              fi
+            else
+              log "FAILED to write the credential into $CONF (helper exit $rc). The WebUI will keep" >&2
+              log "minting a random password every start and BOTH arrs will break. Fix and restart." >&2
+              exit 0
+            fi
+
+            # (3) GROUND TRUTH: the WebUI itself must accept it. Wait for the API to answer at ALL
+            #     (shared ~120s budget across attempts), then spend exactly ONE login per attempt -
+            #     at most 3 rejected logins, which stays under qBittorrent's default ban threshold.
+            #
+            # "THE API NEVER ANSWERED" IS A DIFFERENT FAULT FROM "THE PASSWORD WAS REJECTED", and
+            # conflating them is what made this hook lie once already (see the PORT comment). An
+            # unreachable WebUI is reported as unreachable, and the hook stops rather than spending
+            # its remaining login attempts to produce two more identical wrong diagnoses.
+            api_ok=0
+            while [ "$waited" -lt 120 ]; do
+              code=$(curl -s -o /dev/null -m 3 -w '%{http_code}' "http://127.0.0.1:$PORT/" 2>/dev/null)
+              if [ -n "$code" ] && [ "$code" != "000" ]; then api_ok=1; break; fi
+              waited=$((waited + 1)); sleep 1
+            done
+            if [ "$api_ok" != 1 ]; then
+              log "the WebUI never answered on 127.0.0.1:$PORT within the wait budget, so the" >&2
+              log "credential in $CONF is UNVERIFIED. This is NOT a rejected password - it was" >&2
+              log "never submitted. Do not rotate the credential on the strength of this line." >&2
+              exit 0
+            fi
+            body=$(curl -sS -m 10 \
+                     --data-urlencode "username=$QBT_WEBUI_USERNAME" \
+                     --data-urlencode "password=$QBT_WEBUI_PASSWORD" \
+                     "http://127.0.0.1:$PORT/api/v2/auth/login" 2>/dev/null)
+            if [ "$body" = "Ok." ]; then
+              log "VERIFIED: the WebUI accepts the durable credential for '$QBT_WEBUI_USERNAME'"
+              exit 0
+            fi
+            log "WebUI rejected the durable credential (login said '$body')" >&2
+            # A rejection when the conf was ALREADY converged (rc=0, nothing written) can only mean
+            # the running qbittorrent-nox is serving something it read from an EARLIER conf, so
+            # rewriting the same bytes on the next attempt would change nothing. The remedy is to
+            # make the process RE-READ the file, so restart the supervised service and let the next
+            # attempt re-verify. Without this the retry loop could never change its own outcome.
+            if [ "$(s6-svstat -u "$SVC" 2>/dev/null)" = "true" ]; then
+              log "restarting qbittorrent-nox so it re-reads $CONF, then re-verifying" >&2
+              s6-svc -r "$SVC" || log "s6-svc -r failed (continuing to verify anyway)" >&2
+              sleep 3
+            fi
+          done
+
+          log "GAVE UP after $attempt attempts: the WebUI does not accept the credential from git." >&2
+          # A postStart hook MUST exit 0 - a non-zero exit makes the kubelet KILL the container
+          # (FailedPostStartHook -> CrashLoopBackOff), turning a credential fault into an outage.
+          # Both failure paths above therefore log LOUDLY and exit 0; the `up` SLI still watches the
+          # app, and the arrs' own download-client health check surfaces a broken credential.
+          exit 0
+podSecurityContext:
+  # For the LONGHORN config PVC only, and for the same reason radarr/sonarr set it: fsGroup is a NO-OP
+  # on the NFS volume (the in-tree plugin does no ownership management), but on a Longhorn filesystem
+  # the kubelet applies it, so /config becomes group-writable by the now-uid-1000 process without
+  # depending on the image chowning it. (This image DOES chown: init-qbittorrent-config runs
+  # `lsiown -R abc:abc /config`. Belt and braces — the live /config was 911:911 before this change,
+  # and losing write access to it would lose the WebUI password hash and the session state.)
+  fsGroup: 3000
 exposure: internal              # LAN-only web UI at qbittorrent.${BASE_DOMAIN} (docs/13 row 13; R-DNS/R-NET)
 egress: vpn                     # ALL public egress via node PIA tunnel + kill-switch (docs/03; ADR-0015; R-NET-05/06)
 storage:
@@ -49,7 +358,84 @@ storage:
                                # This is the SAME failure catalog/plex.yaml:54 already records fixing.
                                # The live /config contents were copied onto each PVC before this landed,
                                # so API keys and credentials other apps reference were preserved.
-dependencies: []                # default-deny: reaches only DNS; arr reach it north of its own egress (docs/03; R-NET-01/02)
+  # THE DOWNLOADS AREA — ONE mount of the SAME export sonarr/radarr/plex already consume
+  # (192.168.2.102:/mnt/Storage/plex), narrowed by subPath to the `downloads` subtree and presented at
+  # /downloads, which is precisely where this app is ALREADY configured to write.
+  #
+  # WHY subPath: downloads AND NOT THE EXPORT ROOT AT /media (the shape sonarr/radarr use):
+  #   * LEAST PRIVILEGE, AND IT COSTS NOTHING HERE. A download client has no business writing the
+  #     LIBRARY. The arrs need the root mount because THEY hardlink downloads/ -> tv/ or movies/ and
+  #     link() is a same-MOUNT operation (EXDEV otherwise) — their smallest common ancestor genuinely
+  #     IS the export root. qBittorrent performs no such cross-directory link: it writes into the
+  #     downloads tree and nothing else, so narrowing to that subtree removes movies/, tv/ and photos/
+  #     from this pod's mount namespace without removing any operation it actually performs.
+  #   * HARDLINKS STILL WORK, because they are not done here. The arrs still see ONE mount containing
+  #     both /media/downloads and /media/tv, so their link() stays intra-mount. Proven live 2026-09-12:
+  #     a file created from this pod under /downloads was hardlinked from the sonarr pod between
+  #     /media/downloads/... and /media/tv/... with st_nlink 1 -> 2 and no EXDEV.
+  #   * IT IS ONE MOUNT, so the L0 test `bulk-tier-distinct-from-replicated` assertion (6) — no
+  #     workload mounts one export twice — holds. That assertion is about TWO mounts inside ONE pod;
+  #     a single subPath mount is not the EXDEV trap, two are.
+  #   * The narrowing is a CLIENT/kubelet guarantee, stated honestly: the NFS server still exports the
+  #     whole dataset to this node, so the containment is the mount namespace, not the server's ACLs —
+  #     the same class of caveat docs/BULK-NFS-STORAGE.md §5 records for plex's readOnly.
+  #
+  # NOT readOnly — this is the one workload whose whole job is WRITING here.
+  #
+  # KNOWN, DELIBERATE SIDE EFFECT ON SHARED STATE: the image's init-qbittorrent-config runs
+  # `lsiown abc:abc /downloads` (non-recursive) whenever /downloads is a mount, so starting this pod
+  # chgrps /mnt/Storage/plex/downloads from 1000:1000 to 1000:3000 on the SERVER. Benign and verified:
+  # the directory is mode 0755, whose group bits (r-x) are identical to its other bits, so no consumer
+  # — k3s or legacy — gains or loses any access. Recorded because it is a write to state shared with
+  # non-cluster consumers, which should never be a surprise.
+  #
+  # PATH AGREEMENT WITH THE ARRS IS STILL *NOT* CLOSED — see DECISIONS-LOG 2026-09-12 "Remote Path
+  # Mappings". This pod calls the finished file /downloads/<name>; sonarr/radarr call the same bytes
+  # /media/downloads/<name>. Same inode, different absolute path, so Completed Download Handling needs
+  # ONE Remote Path Mapping per arr (remote host `qbittorrent.qbittorrent.svc.cluster.local`, remote
+  # path /downloads/, local path /media/downloads/).
+  #
+  # THOSE MAPPINGS ARE NOW CONFIGURED AND VERIFIED ON PROD (2026-09-12), together with the qBittorrent
+  # download client itself — which did not exist in EITHER arr until then (both
+  # `GET /api/v3/downloadclient` returned `[]`, so completed-download handling had never been wired up
+  # at all). `downloadclient/testall` reports isValid=true in both, and Sonarr's queue was observed
+  # reporting outputPath=/downloads/... with the mapping deleted and /media/downloads/... with it
+  # present — same torrent, same client.
+  #
+  # BUT THEY LIVE IN THE ARRS' OWN DATABASES (app state on their config PVCs), NOT IN GIT: a rebuild
+  # from git alone does NOT restore them and no gate here notices their absence. The alternative —
+  # repointing qBittorrent's SavePath at /media/downloads and mounting this subPath there instead —
+  # buys path agreement at the cost of editing THIS app's config PVC, which is also app state; it was
+  # not chosen because it changes a running download client's save path, which the deferral above
+  # already shows is easy to get wrong. It is nonetheless the RECOMMENDED end state (it makes the
+  # mappings unnecessary and puts the mountPath half of the fix in git) and is awaiting an operator
+  # decision, not a technical blocker.
+  #
+  # RELATED OPEN BLOCKER: this app has no durable WebUI credential (no WebUI\Username /
+  # WebUI\Password_PBKDF2 in qBittorrent.conf), so v5 issues a NEW temporary `admin` password on every
+  # start. The arrs' saved download-client password therefore goes stale on every pod restart. See the
+  # same DECISIONS-LOG entry for the two fixes, neither of which was taken unilaterally.
+  - name: downloads
+    class: bulk
+    export: /mnt/Storage/plex   # the ZFS dataset Storage/plex, on ${BULK_NFS_SERVER} — the SAME export
+                                # plex (ro) and sonarr/radarr (rw) mount; one dataset, one set of inodes
+    subPath: downloads          # the handoff subtree ONLY: no movies/, no tv/, no photos/
+    mountPath: /downloads       # matches the app's EXISTING Session\DefaultSavePath / TempPath, so no
+                                # change to config-PVC app state is needed to make this take effect
+    size: 9Ti                   # ADVISORY ONLY on a static NFS PV (the ZFS pool is the real limit): the
+                                # dataset's 8.4 T used rounded up, stated the same way plex/sonarr/radarr
+                                # state it so `kubectl get pv` reports something true
+dependencies: []                # default-deny: reaches only DNS; arr reach it north of its own egress (docs/03; R-NET-01/02).
+                                # STILL EMPTY WITH THE NFS MOUNT ABOVE, AND THAT IS CORRECT, NOT AN
+                                # OVERSIGHT. An NFS PersistentVolume is mounted by the NODE KERNEL in the
+                                # HOST netns, not by this pod: there is no pod-side socket to 2049, so no
+                                # CiliumNetworkPolicy can permit or deny it and none is needed. Verified by
+                                # construction — sonarr and radarr have mounted this same export read-write
+                                # for weeks and neither has any CNP naming the NFS server or port 2049
+                                # (grep apps/wave-1/sonarr.yaml: none). The SAME fact is what keeps the VPN
+                                # egress gateway off this traffic (its selector is a podSelector), and
+                                # 192.168.2.102 is inside the 192.168.0.0/16 excludedCIDR besides — see
+                                # platform/vpn-egress/egress-steering.yaml, "BULK NFS".
 ingressRoutes:
  - host: qbittorrent.${BASE_DOMAIN}
    port: 8080                  # qBittorrent WebUI; protected at the Gateway by forward-auth (docs/09, docs/15)
@@ -4,7 +4,8 @@
 Consumes ONE ServiceDefinition (schemas/servicedefinition.schema.json, catalog/*.yaml)
 and emits the concrete manifest set the renderer contract specifies
 (schemas/renderer-contract.md): Namespace + default-deny baseline, Deployment/Service or
-KubeVirt VirtualMachine + CDI DataVolume, PVCs, per-dependency CiliumNetworkPolicy allows,
+KubeVirt VirtualMachine + CDI DataVolume, PVCs, per-dependency and per-in-cluster-client
+CiliumNetworkPolicy allows,
 egress-class steering label, HTTPRoute(s), ServiceMonitor/alerts, Flux image-automation,
 and the auth-mode / backup wiring hints.

@@ -79,7 +80,40 @@ BULK_NFS_SERVER = "${BULK_NFS_SERVER}"
 BULK_NFS_MOUNT_OPTIONS = ["nfsvers=4.1", "hard", "noatime", "timeo=600", "retrans=2"]
 GATEWAY_NAME = "shared"
 GATEWAY_NS = "gateway"
+# ExternalDNS per-resource scoping (R-DNS-03; see _externaldns_route_annotations for the full WHY
+# and for the v0.21.0 source citation). The KEY is external-dns's own `ControllerKey`
+# (annotationPrefix + "controller"); external-dns skips any source object whose value is PRESENT
+# and != `ControllerValue` ("dns-controller"), so the VALUE only has to be some other string.
+# `none` is chosen because it reads as intent in `kubectl get httproute -o yaml` rather than as a
+# typo — "no DNS controller owns this route" — and because the one value that must never be
+# emitted here is external-dns's own, which a literal `none` cannot drift into.
+EXTERNALDNS_CONTROLLER_KEY = "external-dns.alpha.kubernetes.io/controller"
+EXTERNALDNS_CONTROLLER_DISOWN = "none"
+# The value external-dns claims for itself. Held here ONLY so the renderer and the L0 guard can
+# assert the disown value is not it; never emitted.
+EXTERNALDNS_CONTROLLER_CLAIMED = "dns-controller"
 KP_RELEASE = "kube-prometheus-stack"  # ServiceMonitor/PrometheusRule discovery label
+MONITORING_NS = "monitoring"          # where Prometheus runs; the only admitted scrape source
+
+# The kube-state-metrics series a workload's readiness IS (r_prometheusrule). kube-state-metrics
+# is scraped by the bundled kube-prometheus-stack ServiceMonitor, i.e. these exist for EVERY
+# workload in the cluster with no per-service exporter — which is the whole point of using them
+# for `slis: [up]`. Each entry is (metric, label naming the object). VERIFIED on prod 2026-09-13:
+# kube_deployment_status_replicas_available returned a series for all ten deployed app
+# Deployments, and kube_statefulset_status_replicas_ready{namespace="keycloak",
+# statefulset="keycloak"} returned 2.
+LIVENESS_METRICS = {
+    "Deployment": ("kube_deployment_status_replicas_available", "deployment"),
+    "StatefulSet": ("kube_statefulset_status_replicas_ready", "statefulset"),
+    "DaemonSet": ("kube_daemonset_status_number_available", "daemonset"),
+}
+# A KubeVirt VMI is not a replica count: kubevirt_vmi_info carries the phase as a LABEL, so
+# liveness is the EXISTENCE of a running-phase series. The value is lowercase `running` — a
+# capital-R matcher selects nothing and is just as inert (the same trap that made
+# kubevirt_vmi_phase_count{phase="Failed"} a no-op; verified on prod, where the one live VMI
+# reports phase="running").
+VMI_METRIC = "kubevirt_vmi_info"
+VMI_RUNNING_PHASE = "running"

 # egress classes and auth modes fixed by docs/03 / docs/13 + the Kyverno enums.
 EGRESS_CLASSES = ("internet", "vpn")
@@ -116,6 +150,7 @@ def apply_defaults(sd: dict) -> dict:
    s.setdefault("storage", [])
    s.setdefault("dependencies", [])
    s.setdefault("ingressRoutes", [])
+    s.setdefault("inClusterClients", [])

    # auth.mode default posture: forward-auth for any exposed UI, else none (internal, no
    # UI). An explicit auth block always wins (R-IDP-02).
@@ -133,6 +168,26 @@ def apply_defaults(sd: dict) -> dict:
    obs = dict(s.get("observability") or {})
    obs.setdefault("metrics", True)
    obs.setdefault("slis", [])
+    # metricsEndpoint is NEVER defaulted (schema 1.6.0). `metrics: true` says the platform
+    # collects signals FOR this service; it cannot say the workload SERVES a Prometheus
+    # endpoint, because for most of this catalog it does not (see r_servicemonitor). When the
+    # endpoint IS declared, its name/path/interval carry defaults so the common case is
+    # `metricsEndpoint: {port: 9100}`.
+    ep = obs.get("metricsEndpoint")
+    if ep:
+        obs["metricsEndpoint"] = {
+            **{"name": "metrics", "path": "/metrics", "interval": "30s"},
+            **ep,
+        }
+    # livenessWorkload: WHICH Kubernetes object's readiness IS this service being up. Defaulted
+    # from `kind` — a container renders a Deployment named after the service, a vm renders a
+    # VirtualMachine whose VMI carries the same name — and overridable for the case where the
+    # object that actually runs on the cluster is not the one this SD renders (keycloak: the
+    # Keycloak operator runs a StatefulSet, so a Deployment-shaped rule would `absent()` forever).
+    lw = dict(obs.get("livenessWorkload") or {})
+    lw.setdefault("kind", "VirtualMachineInstance" if s["kind"] == "vm" else "Deployment")
+    lw.setdefault("name", s["name"])
+    obs["livenessWorkload"] = lw
    s["observability"] = obs

    # storage entry class default is longhorn (replicated tier); readOnly default is False
@@ -141,6 +196,13 @@ def apply_defaults(sd: dict) -> dict:
    s["storage"] = [{**{"class": "longhorn", "readOnly": False}, **v} for v in s["storage"]]
    # dependency protocol default is tcp.
    s["dependencies"] = [{**{"protocol": "tcp"}, **d} for d in s["dependencies"]]
+    # in-cluster client protocol default is tcp (as for a dependency); its `name` — which only
+    # ever appears in the rendered POLICY name — defaults to the namespace it admits, so the
+    # common case declares just `namespace` + `port` and reads like a dependency edge.
+    s["inClusterClients"] = [
+        {**{"protocol": "tcp", "name": c.get("namespace", "")}, **c}
+        for c in s["inClusterClients"]
+    ]
    return s


@@ -479,7 +541,12 @@ def r_deployment(s: dict) -> dict:

 def r_service(s: dict):
    ports = _service_ports(s)
-    if not ports:
+    # A declared metrics endpoint becomes a NAMED Service port, because that name is the only
+    # thing a ServiceMonitor endpoint can select on. Appended BELOW rather than inside
+    # _service_ports so it never leaks into r_gateway_ingress_policy's north-south allow list —
+    # the metrics port is for the monitoring namespace, not for the Gateway.
+    ep = s["observability"].get("metricsEndpoint")
+    if not ports and not ep:
        return None
    # forward-auth (Option B): the shared Gateway must reach the oauth2-proxy sidecar, so front it
    # with a `authproxy` :4180 Service port (the HTTPRoute backendRef targets this). The app UI/API
@@ -489,6 +556,10 @@ def r_service(s: dict):
        ports = ports + [
            {"name": "authproxy", "port": OAUTH2_PROXY_PORT, "targetPort": OAUTH2_PROXY_PORT}
        ]
+    if ep:
+        ports = ports + [
+            {"name": ep["name"], "port": ep["port"], "targetPort": ep["port"]}
+        ]
    return {
        "apiVersion": "v1",
        "kind": "Service",
@@ -700,13 +771,92 @@ def r_gateway_ingress_policy(s: dict):
    }


+def r_in_cluster_client_policies(s: dict) -> list:
+    """East-west allow: let a declared IN-CLUSTER client reach this service DIRECTLY (R-NET-02).
+
+    `ingressRoutes` opens the NORTH-SOUTH path only — r_gateway_ingress_policy admits the
+    reserved `ingress` identity (the Gateway proxy) and nothing else — and `dependencies`
+    compiles edges only BETWEEN CATALOG SERVICES (both halves are rendered from a catalog
+    entry's own declaration). A PLATFORM CONTROLLER that dials this service's ClusterIP
+    directly therefore had no authorable form at all, and under default-deny (R-NET-01) it is
+    DROPPED.
+
+    That gap is not theoretical: prod's `flux-system` source-controller clones the platform's
+    own repo from the in-cluster Gitea Service (clusters/prod/kustomization.yaml pins
+    `url: http://gitea.gitea.svc.cluster.local:3000/...` so prod's GitOps depends on neither
+    public DNS, Cloudflare, its own Gateway nor ${BASE_DOMAIN}). gitea-allow-gateway-ingress
+    admits `fromEntities: [ingress]` only, so the clone was denied, the source could not
+    reconcile — and the HTTPRoute that would have served a public name instead lives in a
+    DOWNSTREAM tier that cannot apply while the source is down. Source down -> routes never
+    rename -> source stays down. It had to be broken with a live `kubectl apply`, i.e. with a
+    cluster object outside git, which one `kubectl delete` or one rebuild would take away.
+
+    Each entry renders ONE least-privilege ingress CiliumNetworkPolicy, shaped exactly like the
+    reciprocal-dependency half (r_reverse_dependency_policies) but selecting the client by
+    NAMESPACE alone, because a platform controller's pod labels are the upstream chart's to
+    change and are not part of this platform's contract: `fromEndpoints` carrying ONLY the
+    reserved `k8s:io.kubernetes.pod.namespace` label, `toPorts` carrying ONLY the declared
+    port/protocol. Never `fromEntities: all`, and never the whole service. Additive: the
+    namespace default-deny baseline keeps denying every undeclared source and port.
+
+    The policy NAME is `<service>-allow-<name>-ingress`, `name` defaulting to the namespace —
+    it is operator-facing (`kubectl get cnp`, a Hubble drop), and letting an author pin it is
+    what allows an allowance that already had to be applied live to be authored under its
+    EXISTING name, so Flux adopts that object in place rather than creating a near-duplicate
+    beside it and leaving the live one unmanaged.
+    """
+    out = []
+    for client in s["inClusterClients"]:
+        proto = client.get("protocol", "tcp").upper()
+        out.append(
+            {
+                "apiVersion": "cilium.io/v2",
+                "kind": "CiliumNetworkPolicy",
+                "metadata": {
+                    "name": f"{s['name']}-allow-{client['name']}-ingress",
+                    "namespace": s["name"],
+                    "labels": {"app.kubernetes.io/name": s["name"]},
+                },
+                "spec": {
+                    "endpointSelector": {
+                        "matchLabels": {"app.kubernetes.io/name": s["name"]}
+                    },
+                    "ingress": [
+                        {
+                            "fromEndpoints": [
+                                {
+                                    "matchLabels": {
+                                        "k8s:io.kubernetes.pod.namespace": client[
+                                            "namespace"
+                                        ]
+                                    }
+                                }
+                            ],
+                            "toPorts": [
+                                {
+                                    "ports": [
+                                        {"port": str(client["port"]), "protocol": proto}
+                                    ]
+                                }
+                            ],
+                        }
+                    ],
+                },
+            }
+        )
+    return out
+
+
 def _route_meta(s: dict, route: dict) -> dict:
+    """HTTPRoute metadata: auth wiring hints PLUS the ExternalDNS scoping derived from
+    `exposure` (_externaldns_route_annotations — R-DNS-03: an `internal` service renders no
+    public DNS record, and now cannot)."""
    meta = {
        "name": f"{s['name']}-{route['port']}",
        "namespace": s["name"],
        "labels": {"app.kubernetes.io/name": s["name"]},
    }
-    ann = _auth_annotations(s)
+    ann = {**_auth_annotations(s), **_externaldns_route_annotations(s)}
    if ann:
        meta["annotations"] = ann
    return meta
@@ -904,8 +1054,92 @@ def _auth_annotations(s: dict) -> dict:
    return {}


+def _externaldns_route_annotations(s: dict) -> dict:
+    """ExternalDNS scoping, rendered FROM `exposure` (renderer-contract §exposure; R-DNS-03).
+
+    `internal` renders NO public DNS record. That sentence was in the contract from the start and
+    nothing enforced it: ExternalDNS watched EVERY HTTPRoute the shared Gateway carried, so an
+    `internal` service's route published `<name>.${BASE_DOMAIN}` into the PUBLIC authoritative
+    Cloudflare zone, answering with the Gateway VIP — an RFC1918 address. Six of them did
+    (jackett, pihole, qbittorrent, radarr, semaphore, sonarr), which published the internal
+    subnet, the Gateway VIP and a full service inventory to anyone who asked, and made every one
+    of those names a DNS-rebind primitive that the SOHO router strips on the way back in.
+
+    THE MECHANISM, verified against the DEPLOYED version (chart >=1.21.0 <1.22.0, app v0.21.0 —
+    `registry.k8s.io/external-dns/external-dns:v0.21.0`, read off the live prod Deployment), not
+    from memory. external-dns v0.21.0 `source/annotations/processors.go`:
+
+        func IsControllerMismatch(entity metav1.ObjectMetaAccessor, rType string) bool {
+            value, ok := entity.GetObjectMeta().GetAnnotations()[ControllerKey]
+            if ok && value != ControllerValue { ...; return true }
+            return false
+        }
+
+    with `ControllerKey = "external-dns.alpha.kubernetes.io/controller"` and
+    `ControllerValue = "dns-controller"`. `source/gateway.go` calls it per route inside
+    `Endpoints()`, BEFORE any hostname is resolved:
+
+        if annotations.IsControllerMismatch(meta, src.rtKind) { continue }
+
+    so an HTTPRoute carrying any other value is not merely unpublished — it never becomes an
+    endpoint at all, for any hostname it names. `source/service.go` applies the identical check,
+    so the same annotation scopes the `service` source too if a rendered Service ever grows an
+    external-dns hostname.
+
+    WHY THIS IS STRUCTURAL AND NOT INCIDENTAL. The annotation is derived HERE, from `exposure`,
+    with no per-service list anywhere: every HTTPRoute this renderer emits for an `internal`
+    service carries it, and ci/render-golden.sh proves `apps/` reproduces byte-for-byte from
+    `catalog/`, so an `internal` service cannot EXIST in the applied tree without it. Flipping
+    `exposure: internal` to `public` is the only edit that can publish a name, which is exactly
+    the operator-facing declaration R-DNS-03 is written in terms of. The L0 check
+    conformance/tests/l0-static/internal-services-publish-no-public-dns re-proves all of that on
+    every gate run, including that this function reads `exposure` rather than naming services.
+
+    WHY NOT A CLUSTER-WIDE OPT-IN FILTER (`--label-filter`, chart `labelFilter`). It exists, and
+    v0.21.0's own `--help` names both sources in use as supporting it ("currently supported by
+    source types crd, gateway-httproute, ... service and ambassador-host"), so a "publish only
+    what is labelled" posture is available and is STRONGER by default. It is not taken here
+    because its blast radius is not this defect's: seven published names come from hand-authored
+    platform/apps manifests that carry no `exposure` field and that this renderer never sees
+    (auth/oauth2-proxy, crafty + crafty-mc, grafana, headlamp, the homepage apex, unifi). An
+    opt-in filter DELETES all seven the moment it is set, and whether each should stay published
+    is an operator decision, not a renderer one. Per-resource exclusion has exactly the blast
+    radius of the reported defect. The filter remains the available hardening once those seven
+    are adjudicated — see platform/externaldns/helmrelease.yaml.
+    """
+    if s["exposure"] == "internal":
+        return {EXTERNALDNS_CONTROLLER_KEY: EXTERNALDNS_CONTROLLER_DISOWN}
+    return {}
+
+
 def r_servicemonitor(s: dict):
-    if not s["observability"]["metrics"]:
+    """ServiceMonitor — rendered ONLY when the SD says WHERE metrics are served.
+
+    THIS FUNCTION USED TO RENDER A MONITOR UNCONDITIONALLY FROM `metrics: true`, hardcoding
+    `endpoints: [{port: metrics}]`. No Service this renderer emits had ever defined a port of
+    that name, so all twelve monitors discovered ZERO targets: no `up{job="<app>"}` series
+    existed anywhere, `up{job="<app>"} == 0` could not fire, and `PrometheusTargetsMissing`
+    could not see the hole either, because a target that was never discovered has no `up` series
+    to be 0. Verified on prod 2026-09-13: `count by (job) (up)` listed 24 jobs and not one of
+    the twelve appeared; `up{job="plex"}` and `up{job="gitea"}` both returned nothing.
+
+    THE ROOT CAUSE WAS NOT A TYPO — it was that `metrics: true` cannot state a fact the workload
+    does not have. Plex, Pi-hole, Jackett, qBittorrent, Sonarr, Radarr, Seerr, Semaphore and
+    Nextcloud serve no Prometheus endpoint at all without a separate exporter; Gitea can serve
+    one but only once its app.ini enables it. So the port name was never the missing piece. A
+    monitor is now rendered only from `observability.metricsEndpoint`, which names the port the
+    workload actually serves — and that same declaration renders the Service port (r_service) and
+    the monitoring-namespace ingress allow (r_monitoring_ingress_policy), so the three halves of
+    a working scrape cannot be authored apart.
+
+    `metrics: true` still means something without it: logs ship to Loki via the node agent, and
+    liveness comes from kube-state-metrics (r_prometheusrule) — neither needs a per-service CR.
+    """
+    obs = s["observability"]
+    if not obs["metrics"]:
+        return None
+    ep = obs.get("metricsEndpoint")
+    if not ep:
        return None
    return {
        "apiVersion": "monitoring.coreos.com/v1",
@@ -918,7 +1152,108 @@ def r_servicemonitor(s: dict):
        "spec": {
            "selector": {"matchLabels": {"app.kubernetes.io/name": s["name"]}},
            "namespaceSelector": {"matchNames": [s["name"]]},
-            "endpoints": [{"port": "metrics", "interval": "30s"}],
+            "endpoints": [
+                {"port": ep["name"], "path": ep["path"], "interval": ep["interval"]}
+            ],
+        },
+    }
+
+
+def r_monitoring_ingress_policy(s: dict):
+    """Let the monitoring namespace reach a declared metrics port (R-NET-02, R-OBS-01).
+
+    renderer-contract.md has always said the default-deny baseline carries "a standing allow ...
+    for observability scraping from the monitoring namespace" — and no renderer output ever did.
+    Every app namespace ships `ingress: []`, so a scrape of an app metrics port would be DROPPED
+    by policy even with the Service port and the monitor endpoint in agreement. That is the same
+    trap Longhorn's own NetworkPolicies set (platform/longhorn/networkpolicy-metrics.yaml exists
+    for exactly this reason), and it is a THIRD independent way for a metrics SLI to be inert.
+
+    Rendered only alongside a declared metricsEndpoint, and it opens ONLY that port to ONLY the
+    monitoring namespace: an allow for a port nothing serves would be a standing hole for no
+    benefit.
+    """
+    ep = s["observability"].get("metricsEndpoint")
+    if not ep or not s["observability"]["metrics"]:
+        return None
+    return {
+        "apiVersion": "cilium.io/v2",
+        "kind": "CiliumNetworkPolicy",
+        "metadata": {
+            "name": f"{s['name']}-allow-monitoring-scrape",
+            "namespace": s["name"],
+            "labels": {"app.kubernetes.io/name": s["name"]},
+        },
+        "spec": {
+            "endpointSelector": {"matchLabels": {"app.kubernetes.io/name": s["name"]}},
+            "ingress": [
+                {
+                    "fromEndpoints": [
+                        {"matchLabels": {"k8s:io.kubernetes.pod.namespace": MONITORING_NS}}
+                    ],
+                    "toPorts": [
+                        {"ports": [{"port": str(ep["port"]), "protocol": "TCP"}]}
+                    ],
+                }
+            ],
+        },
+    }
+
+
+def _up_sli_rule(s: dict) -> dict:
+    """`slis: [up]` -> a `<name>-down` alert against a signal THAT EXISTS on this cluster.
+
+    IT USED TO READ `up{job="<name>"} == 0`. That is the textbook expression and it was inert
+    for all twelve services in the catalog, because `up` only exists for a target Prometheus
+    actually DISCOVERED and the rendered ServiceMonitor discovered none (see r_servicemonitor).
+    Worse than a wrong threshold: an inert rule and a correct rule are indistinguishable on a
+    healthy cluster, and the generic safety net cannot see the difference either — a target that
+    was never discovered has no `up` series for PrometheusTargetsMissing to find at 0.
+
+    Rewriting the SLI against the app's own /metrics was NOT an option for most of this catalog:
+    Plex, Pi-hole, Jackett, qBittorrent, Sonarr, Radarr, Seerr, Semaphore and Nextcloud export no
+    Prometheus metrics without a separate exporter sidecar per app. So the `up` SLI is expressed
+    against kube-state-metrics, which IS scraped and DOES carry a series for every workload — the
+    same idiom KeycloakDown in platform/monitoring/alerts.yaml has used since it was fixed.
+
+    The `or absent(...)` half is deliberate and load-bearing: it makes the DISAPPEARANCE of the
+    signal fire the alert instead of silencing it. A rule that can only fire on `== 0` is a rule
+    that goes quiet when the workload object (or kube-state-metrics) vanishes, which is precisely
+    how the old expression failed. It is also why this rule cannot be permanently firing where the
+    workload exists: the series is present and non-zero on a healthy cluster (verified on prod).
+    """
+    lw = s["observability"]["livenessWorkload"]
+    kind, obj = lw["kind"], lw["name"]
+    ns = s["name"]
+    if kind == "VirtualMachineInstance":
+        sel = f'{VMI_METRIC}{{namespace="{ns}", name="{obj}", phase="{VMI_RUNNING_PHASE}"}}'
+        expr = f"absent({sel})"
+        desc = (
+            f"{s['name']}: no KubeVirt VMI in phase {VMI_RUNNING_PHASE} for 5m "
+            f"(SLI: up, via {VMI_METRIC})."
+        )
+    else:
+        try:
+            metric, label = LIVENESS_METRICS[kind]
+        except KeyError:
+            raise ValueError(
+                f"{s['name']}: observability.livenessWorkload.kind {kind!r} has no liveness "
+                f"metric; known kinds: {sorted(LIVENESS_METRICS)} + VirtualMachineInstance"
+            ) from None
+        sel = f'{metric}{{namespace="{ns}", {label}="{obj}"}}'
+        expr = f"{sel} == 0 or absent({sel})"
+        desc = (
+            f"{s['name']}: its {kind} has no available/ready replica for 5m, or the signal is "
+            f"gone entirely (SLI: up, via {metric})."
+        )
+    return {
+        "alert": f"{s['name']}-down".replace("_", "-"),
+        "expr": expr,
+        "for": "5m",
+        "labels": {"severity": "critical", "service": s["name"]},
+        "annotations": {
+            "summary": f"{s['name']} is down",
+            "description": desc,
        },
    }

@@ -931,18 +1266,7 @@ def r_prometheusrule(s: dict):
    rules = []
    for sli in slis:
        if sli == "up":
-            rules.append(
-                {
-                    "alert": f"{s['name']}-down".replace("_", "-"),
-                    "expr": f'up{{job="{s["name"]}"}} == 0',
-                    "for": "5m",
-                    "labels": {"severity": "critical", "service": s["name"]},
-                    "annotations": {
-                        "summary": f"{s['name']} is down",
-                        "description": f"{s['name']} has been unreachable for 5m (SLI: up).",
-                    },
-                }
-            )
+            rules.append(_up_sli_rule(s))
        else:
            rules.append(
                {
@@ -1292,6 +1616,25 @@ def render(sd: dict, image_automation: bool = True, inbound: list | None = None)
            )
        )

+    for cnp in r_in_cluster_client_policies(s):
+        docs.append(
+            (
+                "CiliumNetworkPolicy in-cluster client ingress allow (R-NET-02): "
+                f"{cnp['metadata']['name']}",
+                cnp,
+            )
+        )
+
+    mon_allow = r_monitoring_ingress_policy(s)
+    if mon_allow:
+        docs.append(
+            (
+                "CiliumNetworkPolicy monitoring scrape ingress allow (R-NET-02/R-OBS-01): "
+                f"{mon_allow['metadata']['name']}",
+                mon_allow,
+            )
+        )
+
    ie = r_internet_egress(s)
    docs.append(
        (
@@ -1409,6 +1752,25 @@ EXTRA_UNITS: dict = {
            "gitea-actions-runner-secret.sops.yaml",
        ],
    },
+    # PiHole's DNS exposure: the udp/53 + tcp/53 LoadBalancer Services on a pinned VIP, plus the
+    # narrow LAN ingress CiliumNetworkPolicy that admits them (apps/wave-0/pihole-dns.yaml).
+    # `above: False` co-locates it in pihole's OWN wave: these are the pihole pod's own Services and
+    # its own policy, applied in the same wave as the Deployment they select, exactly as the
+    # rendered Service and CNPs in pihole.yaml are. It is NOT a runtime prerequisite of anything, so
+    # there is nothing for a higher wave to gate on.
+    #
+    # It is a non-catalog unit because the ServiceDefinition schema cannot express a LoadBalancer
+    # Service, a pinned lbipam VIP, a sharing key or UDP exposure at all (additionalProperties is
+    # false, and `ingressRoutes` only renders HTTPRoutes on the L7 Gateway) — the same reason
+    # apps/vms/unifi/50-service-l4.yaml and platform/crafty/service-l4.yaml are hand-written. The
+    # split-horizon ANSWERS are in the catalog, as FTLCONF env on catalog/pihole.yaml.
+    "pihole-dns": {
+        "anchor": "pihole",
+        "above": False,
+        "files": [
+            "pihole-dns.yaml",
+        ],
+    },
 }


@@ -1482,6 +1844,10 @@ def plan_apps_waves(sds: list, present_files: set) -> dict:
    convention:
      - `<svc>.yaml`                        -> wave(svc)
      - `<svc>-bootstrap-secret.sops.yaml`  -> wave(svc)   (consumed by svc's env, same apply)
+      - `<svc>-claim-secret.sops.yaml`      -> wave(svc)   (a one-shot upstream-service claim token
+        consumed by svc's env — plex's plex.tv claim. Same wave as the app for the same reason the
+        bootstrap secret is: an env `secretKeyRef` has no `optional`, so the Secret must be applied
+        in the SAME reconcile as the workload or the pod is CreateContainerConfigError.)
      - `<svc>-oauth2-proxy-credentials.sops.yaml` -> wave(svc)  (forward-auth sidecar OIDC creds)
      - `<svc>-db.yaml`                     -> wave(svc-db) (a strictly-lower wave; CNPG DB)
      - `<svc>-db-app.sops.yaml`            -> wave(svc-db) (CNPG initdb owner secret)
@@ -1508,6 +1874,11 @@ def plan_apps_waves(sds: list, present_files: set) -> dict:
        w = waves[name]
        add(w, f"{name}.yaml")
        add(w, f"{name}-bootstrap-secret.sops.yaml")
+        # A one-shot claim token for an UPSTREAM service (plex's plex.tv claim). Same wave as the
+        # app: it is read by the app's env at pod start, and an env secretKeyRef has no `optional`,
+        # so a Secret applied in a later wave would leave the pod in CreateContainerConfigError.
+        # Placed only when the file exists, so services without one are unaffected.
+        add(w, f"{name}-claim-secret.sops.yaml")
        # forward-auth (Option B): the per-app oauth2-proxy sidecar's OIDC client + cookie secret.
        # Same wave as the app (the sidecar reads it at pod start); placed only when the file exists,
        # so non-forward-auth apps are unaffected. Mirrors the bootstrap-secret naming convention.
@@ -1808,6 +2179,191 @@ def _selftest() -> int:
        "a non-exposed service must not render a gateway-ingress allow (least privilege)",
    )

+    # 4b-dns) exposure -> ExternalDNS SCOPING on the HTTPRoute (R-DNS-03). `internal` renders no
+    #     public DNS record and must be INCAPABLE of rendering one: its route carries
+    #     external-dns's own controller annotation set to something other than `dns-controller`,
+    #     which v0.21.0's gateway-httproute source (source/gateway.go ->
+    #     annotations.IsControllerMismatch) uses to skip the route before any hostname is
+    #     resolved. `public` must NOT carry it, or the five public names would vanish instead.
+    #     Both directions are asserted here because only asserting the internal half would pass
+    #     just as happily if the renderer stamped EVERY route and silently unpublished the zone.
+    dns_int_docs = render(
+        {
+            "name": "di",
+            "source": {"image": "a:1"},
+            "exposure": "internal",
+            "ingressRoutes": [{"host": "di.home.keithjackson.dev", "port": 80}],
+            "auth": {"mode": "none"},
+        }
+    )
+    dns_int_routes = [d[1] for d in dns_int_docs if d[1]["kind"] == "HTTPRoute"]
+    check(
+        len(dns_int_routes) == 1,
+        "an internal exposed service must still render its HTTPRoute (LAN reachability is "
+        "unchanged — only the PUBLIC record is withdrawn)",
+    )
+    if dns_int_routes:
+        iann = dns_int_routes[0]["metadata"].get("annotations", {})
+        check(
+            iann.get(EXTERNALDNS_CONTROLLER_KEY) == EXTERNALDNS_CONTROLLER_DISOWN,
+            "an internal service's HTTPRoute must carry the ExternalDNS disown annotation",
+        )
+        check(
+            iann.get(EXTERNALDNS_CONTROLLER_KEY) != EXTERNALDNS_CONTROLLER_CLAIMED,
+            "the disown value must never be external-dns's own `dns-controller` (that CLAIMS "
+            "the route rather than releasing it — the one value that inverts the guarantee)",
+        )
+    dns_pub_docs = render(
+        {
+            "name": "dp",
+            "source": {"image": "a:1"},
+            "exposure": "public",
+            "ingressRoutes": [{"host": "dp.home.keithjackson.dev", "port": 80}],
+            "auth": {"mode": "native"},
+        }
+    )
+    dns_pub_routes = [d[1] for d in dns_pub_docs if d[1]["kind"] == "HTTPRoute"]
+    check(len(dns_pub_routes) == 1, "a public service must render its HTTPRoute")
+    if dns_pub_routes:
+        check(
+            EXTERNALDNS_CONTROLLER_KEY
+            not in dns_pub_routes[0]["metadata"].get("annotations", {}),
+            "a public service's HTTPRoute must NOT carry the ExternalDNS disown annotation",
+        )
+    # The DEFAULT posture is `internal` (renderer-contract "Default posture"), so a
+    # ServiceDefinition that simply omits `exposure` must also be unpublishable. Omitting the
+    # field is the likeliest way a new service arrives, and it is the case a per-service
+    # allow-list would miss.
+    dns_dflt_docs = render(
+        {
+            "name": "dd",
+            "source": {"image": "a:1"},
+            "ingressRoutes": [{"host": "dd.home.keithjackson.dev", "port": 80}],
+            "auth": {"mode": "none"},
+        }
+    )
+    dns_dflt_route = next(d[1] for d in dns_dflt_docs if d[1]["kind"] == "HTTPRoute")
+    check(
+        dns_dflt_route["metadata"]["annotations"].get(EXTERNALDNS_CONTROLLER_KEY)
+        == EXTERNALDNS_CONTROLLER_DISOWN,
+        "a ServiceDefinition that OMITS `exposure` defaults to internal and must also be "
+        "unpublishable (default posture, renderer-contract)",
+    )
+    # The scoping annotation must COEXIST with the auth hints rather than replace them: both are
+    # merged into one `annotations` map, and a forward-auth internal app is the overlap case.
+    dns_fa_docs = render(
+        {
+            "name": "df",
+            "source": {"image": "a:1"},
+            "exposure": "internal",
+            "ingressRoutes": [{"host": "df.home.keithjackson.dev", "port": 80}],
+            "auth": {"mode": "forward-auth", "groups": ["platform-admins"]},
+        }
+    )
+    dns_fa_ann = next(
+        d[1] for d in dns_fa_docs if d[1]["kind"] == "HTTPRoute"
+    )["metadata"]["annotations"]
+    check(
+        dns_fa_ann.get(EXTERNALDNS_CONTROLLER_KEY) == EXTERNALDNS_CONTROLLER_DISOWN
+        and dns_fa_ann.get(f"{LBL}/auth-mode") == "forward-auth",
+        "DNS scoping and auth-mode hints must COEXIST on one internal forward-auth route",
+    )
+
+    # 4c) inClusterClients -> one ADDITIVE, least-privilege ingress allow per entry that admits a
+    #     PLATFORM controller's NAMESPACE (not the reserved `ingress` identity, not `all`) to ONE
+    #     declared port. This is what keeps a cluster whose GitOps source is an in-cluster Service
+    #     reconcilable: fromEntities[ingress] does not cover a controller dialling the ClusterIP.
+    icc_docs = render(
+        {
+            "name": "g",
+            "source": {"image": "a:1"},
+            "ingressRoutes": [{"host": "g.home.keithjackson.dev", "port": 3000}],
+            "auth": {"mode": "none"},
+            "inClusterClients": [
+                {"name": "flux", "namespace": "flux-system", "port": 3000}
+            ],
+        }
+    )
+    icc = [
+        d[1]
+        for d in icc_docs
+        if d[1]["kind"] == "CiliumNetworkPolicy"
+        and d[1]["metadata"]["name"] == "g-allow-flux-ingress"
+    ]
+    check(
+        len(icc) == 1,
+        "an inClusterClients entry must render one ingress CNP named "
+        "<service>-allow-<name>-ingress",
+    )
+    if icc:
+        p = icc[0]
+        check(
+            p["metadata"]["namespace"] == "g"
+            and p["spec"]["endpointSelector"]["matchLabels"]
+            == {"app.kubernetes.io/name": "g"},
+            "in-cluster client allow must live in the service's namespace and select the service",
+        )
+        ing = p["spec"]["ingress"]
+        check(
+            ing[0]["fromEndpoints"]
+            == [{"matchLabels": {"k8s:io.kubernetes.pod.namespace": "flux-system"}}],
+            "in-cluster client allow must match the client NAMESPACE only (reserved k8s: label)",
+        )
+        check(
+            "fromEntities" not in ing[0],
+            "in-cluster client allow must not widen to an entity (never fromEntities: all)",
+        )
+        icc_ports = {
+            (pt["port"], pt["protocol"])
+            for r in ing
+            for tp in r["toPorts"]
+            for pt in tp["ports"]
+        }
+        check(
+            icc_ports == {("3000", "TCP")},
+            "in-cluster client allow must be least-privilege (only the declared port/protocol)",
+        )
+    # ADDITIVE: default-deny ingress stays [] and the gateway allow is untouched.
+    icc_dd = next(d[1] for d in icc_docs if d[1]["kind"] == "NetworkPolicy")
+    check(
+        icc_dd["spec"]["ingress"] == [],
+        "in-cluster client allow must be ADDITIVE — default-deny ingress stays [] (R-NET-01)",
+    )
+    check(
+        any(
+            d[1]["metadata"].get("name") == "g-allow-gateway-ingress"
+            for d in icc_docs
+            if d[1]["kind"] == "CiliumNetworkPolicy"
+        ),
+        "in-cluster client allow must not displace the north-south gateway allow",
+    )
+    # `name` is OPTIONAL and defaults to the namespace, so the common case is namespace + port.
+    icc_default = render(
+        {
+            "name": "g",
+            "source": {"image": "a:1"},
+            "inClusterClients": [{"namespace": "monitoring", "port": 9090}],
+        }
+    )
+    check(
+        any(
+            d[1]["metadata"].get("name") == "g-allow-monitoring-ingress"
+            for d in icc_default
+            if d[1]["kind"] == "CiliumNetworkPolicy"
+        ),
+        "inClusterClients.name must default to the admitted namespace",
+    )
+    # A service that declares none must render NO such policy (grant-nothing-extra).
+    check(
+        not any(
+            d[1]["kind"] == "CiliumNetworkPolicy"
+            and d[1]["metadata"]["name"].endswith("-ingress")
+            and "fromEndpoints" in d[1]["spec"].get("ingress", [{}])[0]
+            for d in render({"name": "q", "source": {"image": "a:1"}})
+        ),
+        "a service declaring no inClusterClients must render no in-cluster client allow",
+    )
+
    # 5) vm kind -> VirtualMachine + standalone DataVolume.
    vm_docs = render(
        {
@@ -2001,7 +2557,8 @@ def _selftest() -> int:
    # 7a) plan_apps_waves: sidecars inherit their unit's wave; not-onboarded SDs are skipped;
    #     EXTRA_UNITS anchor strictly above; a file absent from the tree is never placed.
    present = {
-        "a.yaml", "svc.yaml", "svc-bootstrap-secret.sops.yaml",
+        "a.yaml", "a-claim-secret.sops.yaml",
+        "svc.yaml", "svc-bootstrap-secret.sops.yaml",
        "svc-db.yaml", "svc-db-app.sops.yaml", "svc-db-backup-credentials.sops.yaml",
        "svc-db-backup-credentials-prod.sops.yaml",
        "gitea.yaml",
@@ -2012,6 +2569,10 @@ def _selftest() -> int:
    plan = plan_apps_waves(plan_sds, present)
    flat = {f: wv for wv, fs in plan.items() for f in fs}
    check(flat.get("a.yaml") == 0, "leaf app must land in wave 0")
+    check(flat.get("a-claim-secret.sops.yaml") == 0,
+          "a `<svc>-claim-secret.sops.yaml` (plex's plex.tv claim) must be placed in the SAME wave "
+          "as its app — an env secretKeyRef has no `optional`, so a later wave means "
+          "CreateContainerConfigError")
    check(flat.get("svc-db.yaml") == 0 and flat.get("svc-db-app.sops.yaml") == 0
          and flat.get("svc-db-backup-credentials.sops.yaml") == 0
          and flat.get("svc-db-backup-credentials-prod.sops.yaml") == 0,
@@ -2126,6 +2687,154 @@ def _selftest() -> int:
        "the escaped `$${...}` form must render (and reach the shell as `${...}`)",
    )

+    # 9) observability (R-OBS-01): `metrics: true` alone renders NO ServiceMonitor, and the `up`
+    #    SLI reads a signal that exists. This is the regression test for the defect that made all
+    #    twelve `<app>-down` rules structurally inert on prod (see r_servicemonitor).
+    obs_sd = {
+        "name": "obsdemo",
+        "source": {"image": "a:1"},
+        "ingressRoutes": [{"host": "obsdemo.${BASE_DOMAIN}", "port": 8080}],
+        "auth": {"mode": "none"},
+        "observability": {"metrics": True, "slis": ["up"]},
+    }
+    obs_docs = render(obs_sd)
+    check(
+        not [d for d in obs_docs if d[1]["kind"] == "ServiceMonitor"],
+        "metrics: true with NO metricsEndpoint must render no ServiceMonitor — a monitor naming a "
+        "port the Service does not define discovers zero targets and makes the SLI inert",
+    )
+    pr = next(d[1] for d in obs_docs if d[1]["kind"] == "PrometheusRule")
+    up_rule = pr["spec"]["groups"][0]["rules"][0]
+    check(up_rule["alert"] == "obsdemo-down", "slis: [up] must render <name>-down")
+    check(
+        "up{job=" not in up_rule["expr"],
+        "the up SLI must NOT read up{job=...}: no repo-rendered scrape target produces that job, "
+        "so the rule can never fire (verified inert on prod for all twelve apps)",
+    )
+    check(
+        up_rule["expr"]
+        == 'kube_deployment_status_replicas_available{namespace="obsdemo", deployment="obsdemo"} '
+        '== 0 or absent(kube_deployment_status_replicas_available{namespace="obsdemo", '
+        'deployment="obsdemo"})',
+        "container up SLI must read kube_deployment_status_replicas_available with an absent() "
+        f"half; got: {up_rule['expr']}",
+    )
+
+    # 9a) livenessWorkload override: the object that RUNS is not always the one this SD renders.
+    sts_docs = render(
+        dict(
+            obs_sd,
+            name="obssts",
+            observability={
+                "metrics": True,
+                "slis": ["up"],
+                "livenessWorkload": {"kind": "StatefulSet", "name": "obssts"},
+            },
+        )
+    )
+    sts_expr = next(
+        d[1] for d in sts_docs if d[1]["kind"] == "PrometheusRule"
+    )["spec"]["groups"][0]["rules"][0]["expr"]
+    check(
+        "kube_statefulset_status_replicas_ready" in sts_expr,
+        f"livenessWorkload kind StatefulSet must read the statefulset series; got: {sts_expr}",
+    )
+
+    # 9b) vm kind: a VMI has no replica count, so liveness is a running-phase series EXISTING.
+    vm_pr = next(
+        d[1]
+        for d in render(
+            {
+                "name": "obsvm",
+                "kind": "vm",
+                "source": {"vmTemplate": "quay.io/x/y:1"},
+                "storage": [{"name": "root", "size": "6Gi"}],
+                "observability": {"metrics": True, "slis": ["up"]},
+            }
+        )
+        if d[1]["kind"] == "PrometheusRule"
+    )
+    check(
+        vm_pr["spec"]["groups"][0]["rules"][0]["expr"]
+        == 'absent(kubevirt_vmi_info{namespace="obsvm", name="obsvm", phase="running"})',
+        "vm up SLI must read kubevirt_vmi_info with the LOWERCASE running phase: "
+        f"{vm_pr['spec']['groups'][0]['rules'][0]['expr']}",
+    )
+
+    # 9c) metricsEndpoint renders ALL THREE halves of a working scrape, and they AGREE. Any one of
+    #     them missing is an independent way for the scrape to silently discover/deliver nothing.
+    ep_docs = render(
+        dict(
+            obs_sd,
+            name="obsep",
+            observability={
+                "metrics": True,
+                "slis": ["up"],
+                "metricsEndpoint": {"port": 9100},
+            },
+        )
+    )
+    ep_svc = next(d[1] for d in ep_docs if d[1]["kind"] == "Service")
+    ep_sm = next(d[1] for d in ep_docs if d[1]["kind"] == "ServiceMonitor")
+    svc_port_names = {p["name"] for p in ep_svc["spec"]["ports"]}
+    ep_ports = {e["port"] for e in ep_sm["spec"]["endpoints"]}
+    check(
+        ep_ports <= svc_port_names,
+        f"ServiceMonitor endpoint port(s) {sorted(ep_ports)} must all exist on the Service "
+        f"{sorted(svc_port_names)} — this exact disagreement is what made twelve monitors inert",
+    )
+    check(
+        {"name": "metrics", "port": 9100, "targetPort": 9100} in ep_svc["spec"]["ports"],
+        "metricsEndpoint must render the named Service port it declares",
+    )
+    mon_cnp = [
+        d[1]
+        for d in ep_docs
+        if d[1]["kind"] == "CiliumNetworkPolicy"
+        and d[1]["metadata"]["name"] == "obsep-allow-monitoring-scrape"
+    ]
+    check(
+        len(mon_cnp) == 1,
+        "a declared metricsEndpoint must render the monitoring-namespace ingress allow — the "
+        "namespace default-deny has `ingress: []` and would DROP the scrape without it",
+    )
+    if mon_cnp:
+        ing = mon_cnp[0]["spec"]["ingress"][0]
+        check(
+            ing["fromEndpoints"][0]["matchLabels"]["k8s:io.kubernetes.pod.namespace"]
+            == MONITORING_NS
+            and ing["toPorts"][0]["ports"] == [{"port": "9100", "protocol": "TCP"}],
+            "the scrape allow must admit ONLY the monitoring namespace to ONLY the metrics port",
+        )
+    gw_cnp = next(
+        d[1]
+        for d in ep_docs
+        if d[1]["kind"] == "CiliumNetworkPolicy"
+        and d[1]["metadata"]["name"] == "obsep-allow-gateway-ingress"
+    )
+    gw_ports = {p["port"] for p in gw_cnp["spec"]["ingress"][0]["toPorts"][0]["ports"]}
+    check(
+        "9100" not in gw_ports,
+        "the metrics port must NOT be opened to the Gateway (north-south); it is for the "
+        f"monitoring namespace only. Gateway allows: {sorted(gw_ports)}",
+    )
+    # A metricsEndpoint the renderer cannot express must be REFUSED, never rendered inert.
+    try:
+        render(
+            dict(
+                obs_sd,
+                name="obsbad",
+                observability={
+                    "metrics": True,
+                    "slis": ["up"],
+                    "livenessWorkload": {"kind": "CronJob", "name": "obsbad"},
+                },
+            )
+        )
+        check(False, "an unknown livenessWorkload.kind must raise, not render a bogus expression")
+    except ValueError as exc:
+        check("CronJob" in str(exc), "the refusal must name the unsupported kind")
+
    if failures:
        for f in failures:
            sys.stderr.write(f"SELFTEST FAIL: {f}\n")
@@ -1,5 +1,19 @@
 # `ci/` — portable merge gate (runnable today, without Gitea)

+> **STATUS NOTE (2026-09-29) — read before trusting the "Phase 0" framing below.**
+> This document speaks as though no cluster exists and the platform is scaffolding. **A
+> three-node k3s cluster has existed for weeks** and Flux has been reconciling against it.
+> Gitea is live, the Actions runner `incluster-dind` is online, and `main` is a protected
+> branch. Where the text says "Phase 0", "stub", or "no cluster exists", read it as
+> describing a **live gap** rather than an expected stage — most importantly, L2/L3
+> conformance still does not run in CI (`vars.CLUSTER_AVAILABLE` is unset), which is a real
+> coverage hole, not a phase.
+>
+> This mismatch is not cosmetic. A month of "the gate enforces this" claims rested on
+> documentation rather than measurement, and `main` was unprotected with zero runners
+> registered the whole time. **Query the live API before asserting platform state.**
+
+
 **Task T-0.2 · R-TEST-02 (reproducible, single-command) · Owner WS-GITOPS (CI).**

 The same merge gate the Gitea Actions workflow runs
@@ -27,9 +41,31 @@ make -C ci test        # unit tests for these scripts themselves (ci/tests/*.tes
 ```

 The `l0` stage has three sub-stages: ServiceDefinition schema validation, the Kyverno policy gate
-(`kyverno test`), and **`conformance/run.sh --layer l0`** — the whole-repo L0 invariants a
-per-resource policy cannot express (secret hygiene across every tracked file, least-privilege RBAC,
-spec-immutability enforcement). See `conformance/tests/README.md`.
+(`kyverno test`), and **`conformance/run.sh --layer l0 --include-scope whole-repo`** — the whole-repo
+L0 invariants a per-resource policy cannot express (secret hygiene across every tracked file,
+least-privilege RBAC, spec-immutability enforcement). See `conformance/tests/README.md`.
+
+### `--include-scope whole-repo`: why the L0 sub-stage is not purely requirement-scoped
+
+R-TEST-03 runs the conformance subset a change **touches**. That has one blind spot, and it is the
+worst-shaped kind: an invariant that quantifies over the whole tracked tree, or over subtrees the
+coarse path→requirement map keys to *nothing* (`apps/`, `infra/`, most of `platform/`), cannot be
+selected *by* the requirements a change touches — because **the change most likely to break it
+attributes no requirement at all**. Requirement-scoped selection then filters the check out of
+exactly that change.
+
+This used to be handled by a hand-written "UNCONDITIONAL" stage per such check (3c subst-safety,
+3d keycloak-client-secrets, 3e bulk-tier): three near-identical rationales, three hardcoded
+`check.sh` paths, three copies of the same `rc 0/3/*` case block — and, worse, a mechanism that
+failed **silently**, because whoever added the next whole-repo invariant had to *remember* to write
+a stage. Those stages are gone. A test now **declares** `conformance.home.k3s/scope: "whole-repo"`
+and the runner unions every declaring test into the run. Adding the annotation is the only step.
+
+`rc 3` is preserved exactly as those stages had it: a **SKIP** of a scope-declared check means the
+tree it audits has vanished, so the runner exits `3`, `ci/l0.sh` sets the gate's own `rc=3`, and the
+gate reports SKIPPED — **never a pass**. The mechanism is itself proven, end-to-end and falsifiably,
+by `conformance/tests/l0-static/whole-repo-invariants-wired`; `conformance/lib/common.sh` carries the
+full rationale and the incidents behind it.

 ## Exit-code contract

@@ -37,6 +73,47 @@ Every stage script uses: **`0` = pass · `1` = fail (blocks merge) · `3` = SKIP
 with no cluster, or an unwired seam / missing tool). A `3` is **never** counted as green — that is how
 the gate stays honest in Phase 0 (no fake green).

+### The gate's OWN verdict (changed 2026-09-13 — read this if you consume the exit code)
+
+**`MERGE GATE: PASS` + exit 0 means every stage that was supposed to run RAN and was GREEN.** It
+used to mean less than that: a FAILED stage set the block flag but a SKIPPED one only printed a
+warning, so the gate printed `l0: skipped (unwired seam / missing tool) — not green` and then
+`MERGE GATE: PASS`, exit 0. That happened for real twice — a missing `promtool` (the alert-rule
+unit tests) and a missing pinned `kyverno` CLI — and exit 0 is what automation reads as
+merge-approved. Fail-open in the one component whose whole job is to fail closed.
+
+| verdict | exit | meaning |
+|---|---|---|
+| `MERGE GATE: PASS` | `0` | every stage that was supposed to run ran and was green; the R-TEST-03 subset was checked. Any capability the environment **declared** out of scope is **named in the headline** (see below), so a PASS never implies more than it verified. |
+| `MERGE GATE: BLOCKED` | `1` | a stage FAILED, or a stage did not run **where it must**, or the decision input is unusable. |
+| `MERGE GATE: UNDETERMINED` | `3` | nothing failed, but a stage did not run, so greenness was **not established**. Never a pass; non-zero so nothing can read it as approval. `3` is this repo's existing "not run" code, now spoken by the gate as a whole and not only by its stages. |
+| `MERGE GATE: NOT APPLICABLE` | `0` | there is no branch under gate at all (`HEAD` is on base — a push-to-`main` run). Stages ran; no subset was checked, and the headline says so. |
+
+Precedence: BLOCKED > UNDETERMINED > NOT APPLICABLE > PASS.
+
+**`make` masks the difference.** GNU make reports any recipe failure as its own exit `2`, so
+`make -C ci gate` collapses `1` and `3` into `2` (the headline still tells a human which it was). A
+caller that must distinguish them invokes `./ci/gate.sh` directly.
+
+### Which skips block, and why — a skip is not one thing
+
+| stage | a skip there means | verdict |
+|---|---|---|
+| `lint`, `l0`, `render-golden`, `l1` | a **pinned tool is absent** or a **wired seam went unwired** — it *could not run* | **BLOCKED** under strict skips (a CI runner: the toolchain is installed for us by `.gitea/workflows/scripts/install-tools.sh`, so a skip is a defect); **UNDETERMINED** otherwise (a workstation missing a tool is a real local condition — still non-zero, still not a pass; the remedy is `infra/devcontainer/dev.sh`, which carries the pinned toolchain) |
+| `spec-immutability` (R-TEST-06) | the sibling spec repo is not checked out, so the spec **could not be verified** | **UNDETERMINED** — unverified is unverified. Deliberately *not* upgraded to BLOCKED by strict skips: the live runner does not check the spec repo out at all, so blocking would leave the only enforced status check permanently red for a reason no PR could clear. It is therefore the **one** skip whose non-answer a caller may knowingly tolerate, and `.gitea/workflows/gate.yml` does so in one visible line. `REQUIRE_SPEC_VERIFICATION=true` makes it a hard block once that checkout is wired. Locally: check the spec repo out beside this one, or set `SPEC_REPO` (`dev.sh` mounts a sibling automatically). |
+| `conformance` (L2/L3) | `CLUSTER_AVAILABLE!=true` — the environment **declared** the capability absent (documented Phase-0 behaviour) | **does not deny a PASS**: a declared-inapplicable stage was never *supposed* to run. It is NAMED in the PASS headline and step summary, the touched requirements it would have covered are reported UNVERIFIED, and `REQUIRE_CLUSTER_TESTS=true` (Phase 1+) turns that into a block. A skip **despite** `CLUSTER_AVAILABLE=true` is a defect and BLOCKS. |
+
+That asymmetry is the whole rule: **declared-not-applicable may pass; could-not-run may not.**
+
+`GATE_STRICT_SKIPS=true|false` decides strictness and is **declared, never sniffed** — `gate.yml`
+sets it on the gate step, because the workflow is the thing that knows it is CI. Unset, it falls
+back to `GITHUB_ACTIONS` / `CI` (set by the runner itself). A wrong answer in either direction
+cannot fail open: both branches are non-zero and neither is a PASS. Set it locally to rehearse CI
+strictness.
+
+Locked down by `ci/tests/gate-decision.test.sh` (47 assertions over the decision table: stubbed
+stage outcomes against the real `gate.sh`; 32 of them fail against the pre-2026-09-13 gate).
+
 ### The touched-requirement subset can also be *undeterminable* (exit 3)

 `touched-requirements.sh` is the input to the R-TEST-03 decision. It resolves a diff base in this
@@ -87,6 +164,8 @@ ci/
  lint.sh                  Stage: yaml/lint
  l0.sh                    Stage: schema validation + Kyverno L0 gate + L0 static conformance
  l1.sh                    Stage: L1 rendering checks (Chainsaw L1 via the conformance runner)
+                           (harness: platform/monitoring/tests/). Catches the two alerting bugs no
+                           other stage can see — permanently-firing and structurally INERT rules.
  conformance.sh           Stage: L2/L3 in-cluster Chainsaw Job (trigger + collect)
  touched-requirements.sh  compute the R-* subset a change touches (drives the R-TEST-03 filter);
                           exits 3 LOUDLY rather than guessing when the diff base is unreliable
@@ -122,3 +201,15 @@ its owner delivers a runnable entrypoint.
 `CLUSTER_AVAILABLE=true` (env locally, `vars.CLUSTER_AVAILABLE` in Gitea) makes the L2/L3 stage run and
 be **required**; anything else makes it **SKIP** (Phase 0). `REQUIRE_CLUSTER_TESTS=true` (Phase 1+)
 turns any unverified cluster-needing touched requirement into a hard block.
+
+All four switches are read through one `truthy()` in `lib.sh`, so they spell "on" identically
+(`true|1|yes|y|on`, any case) and — the direction that matters — **anything else is OFF**: a
+misspelled `CLUSTER_AVAILABLE=ture` leaves the capability undeclared instead of silently claiming
+it, which can only make the gate stricter about what it says it verified.
+
+| switch | default | effect |
+|---|---|---|
+| `CLUSTER_AVAILABLE` | `false` | declares a cluster; L2/L3 then run and are required |
+| `REQUIRE_CLUSTER_TESTS` | `false` | Phase 1+: an unverified cluster-needing touched requirement BLOCKS |
+| `REQUIRE_SPEC_VERIFICATION` | `false` | an unverifiable spec repo BLOCKS instead of UNDETERMINED |
+| `GATE_STRICT_SKIPS` | `auto` | `true` = a missing tool / unwired seam BLOCKS (CI); `auto` follows `GITHUB_ACTIONS`/`CI` |
@@ -47,7 +47,11 @@ fi
 # (conformance/lib/common.sh) now unions a comma/space list of layers, so this is a single
 # invocation with one aggregated report (no per-layer looping needed). Artifacts are then
 # COLLECTED from the fixed location below.
-"$CONFORMANCE_CMD" --layer l2,l3 "${req_args[@]}"
+# --include-scope: union the touched subset with every L2/L3 test DECLARING
+# `conformance.home.k3s/scope: whole-repo` (none today — wired once, here, so a future
+# whole-repo behavioural invariant needs only the annotation; see conformance/lib/common.sh).
+: "${WHOLE_REPO_SCOPE:=whole-repo}"
+"$CONFORMANCE_CMD" --layer l2,l3 --include-scope "$WHOLE_REPO_SCOPE" "${req_args[@]}"

 CONF_ART="$(dirname "$CONFORMANCE_CMD")/_artifacts"
 if [ -f "${CONF_ART}/report.junit.xml" ]; then
@@ -7,6 +7,75 @@
 #   skip (3)  not run (cluster-gated stage w/ no cluster, or unwired seam) —
 #             NOT counted as green (HARD RULE 4: don't fake green)
 #
+# ...AND THREE OUTCOMES FOR THE GATE ITSELF (2026-09-13). Until today a stage that
+# SKIPPED only printed a warning ("— not green") and the gate then printed
+# `MERGE GATE: PASS` and exited 0 anyway. That is fail-open in the one component whose
+# entire job is to fail closed: a pinned tool missing from the runner, or a seam silently
+# becoming unwired, produced exit 0 and read as merge-approved. Observed live:
+# `prom-rules: skipped (missing tool) — not green` followed by `MERGE GATE: PASS`, and
+# `l0: skipped (kyverno CLI not installed)` likewise. The gate's own vocabulary already
+# had the answer — the 2026-08-31 "local false green" introduced UNDECIDED for exactly
+# this shape of non-answer — the offline stages just did not use it.
+#
+#   MERGE GATE: PASS           exit 0   every stage that was SUPPOSED TO RUN ran and was
+#                                       green, and the R-TEST-03 subset was checked.
+#   MERGE GATE: BLOCKED        exit 1   a stage FAILED, or a stage did not run WHERE IT
+#                                       MUST (see the per-stage rules below), or the
+#                                       decision input is unusable.
+#   MERGE GATE: UNDETERMINED   exit 3   nothing failed, but a stage did not run, so
+#                                       greenness was NOT ESTABLISHED. Never a pass;
+#                                       non-zero so no automation can read it as approval.
+#                                       `3` is this repo's existing "not run / not
+#                                       established" code (ci/lib.sh), now spoken by the
+#                                       gate as a whole and not only by its stages.
+#   MERGE GATE: NOT APPLICABLE exit 0   there is no branch under gate at all (HEAD is on
+#                                       base) — a push-to-main CI run. Stages were green;
+#                                       no subset was checked, and the headline says so.
+#
+# NOTE ON `make`: GNU make reports ANY recipe failure as its own exit 2, so
+# `make -C ci gate` collapses 1 and 3 into 2 — a human sees the headline and that is enough.
+# A caller that must tell BLOCKED from UNDETERMINED invokes ./ci/gate.sh directly; to tolerate
+# an UNDETERMINED run it writes `./ci/gate.sh || [ $? -eq 3 ]`, the same explicit idiom
+# .gitea/workflows/gate.yml already used for its spec-immutability pre-step and now uses for
+# the gate itself (with GATE_STRICT_SKIPS=true, so that tolerance can ONLY ever cover the
+# declared-environmental skip below — a missing tool on the runner is exit 1, untolerated).
+# TOLERATING A NON-ANSWER IS A VISIBLE, REVIEWED CHOICE IN THE CALLER. There is deliberately no
+# knob inside this script that turns UNDETERMINED into exit 0: that would be the fail-open this
+# change exists to remove, just relocated.
+#
+# WHICH SKIPS BLOCK, AND WHY (per stage — a skip is not one thing):
+#
+#   lint / l0 / render-golden / l1   A skip here means a PINNED tool is absent or a wired
+#     seam went unwired. On a CI runner the pinned toolchain is installed for us by
+#     .gitea/workflows/scripts/install-tools.sh, so a skip there is a DEFECT, not an
+#     environment: it BLOCKS. On a workstation a missing tool is a real local condition, so
+#     it degrades to UNDETERMINED (still non-zero, still never a pass). See strict_skips()
+#     in ci/lib.sh for how CI is detected and why misdetecting it cannot fail open.
+#
+#   spec-immutability (R-TEST-06)    A skip means the sibling spec repo is not checked out, so
+#     the spec COULD NOT BE VERIFIED. Never a pass — unverified is unverified — so it denies a
+#     PASS and yields UNDETERMINED. It is deliberately NOT upgraded to BLOCKED by CI strictness,
+#     because on the live runner it is not a defect anyone can fix from inside this repo: the
+#     workflow does not check the spec repo out at all (SPEC_REPO_SLUG is unwired — the blueprint
+#     lives in merge-gate.yaml), and blocking would leave the only enforced status check
+#     permanently red for a reason no PR could clear. So THIS is the one skip whose non-answer the
+#     CALLER may knowingly tolerate, and gate.yml does so in one visible line. Locally the
+#     remedy exists and the message names it: check the spec repo out beside this one, or point
+#     SPEC_REPO at it (infra/devcontainer/dev.sh mounts it automatically when it is a sibling).
+#     Set REQUIRE_SPEC_VERIFICATION=true (the counterpart of REQUIRE_CLUSTER_TESTS) to make it a
+#     hard block once that checkout is wired.
+#
+#   conformance (L2/L3)              A skip when CLUSTER_AVAILABLE!=true is NOT a defect and
+#     NOT an accident: it is the environment DECLARING that the capability is absent, which
+#     is the documented Phase-0 behaviour. A declared-inapplicable stage was never "supposed
+#     to run", so it does not deny a PASS — the touched requirements it would have covered
+#     are still reported UNVERIFIED, and REQUIRE_CLUSTER_TESTS=true (Phase 1+) turns that
+#     into a block. A skip DESPITE CLUSTER_AVAILABLE=true is a defect and blocks, exactly as
+#     it already did. That asymmetry is the whole distinction this file now draws:
+#     DECLARED-not-applicable may pass; COULD-NOT-RUN may not. A declared gap is still NAMED in
+#     the PASS headline (see DECLARED_GAPS below), so a PASS never reads as "everything was
+#     verified" when a layer was declared out of scope.
+#
 # Phase 0 policy (no cluster): L0/L1 stages (lint, schema, kyverno, L1 render)
 # MUST be green. L2/L3 SKIP. If the touched subset needs L2/L3 and no cluster is
 # available, the gate reports those requirements UNVERIFIED and — unless
@@ -20,6 +89,7 @@ source "${CI_DIR}/lib.sh"
 set +e   # lib.sh enables -e; the gate must run ALL stages and aggregate, not abort.

 : "${REQUIRE_CLUSTER_TESTS:=false}"
+: "${REQUIRE_SPEC_VERIFICATION:=false}"

 declare -A OUTCOME
 run_stage() {
@@ -47,6 +117,13 @@ run_stage conformance   "${CI_DIR}/conformance.sh"
 echo >&2
 log "==== gate decision ===="
 BLOCK=0
+# Stages that did NOT run and are tolerated here — but never as green. A non-empty list
+# means the gate could not establish greenness -> MERGE GATE: UNDETERMINED, exit 3.
+NOT_ESTABLISHED=()
+# Stages the environment DECLARED inapplicable (today: L2/L3 with no cluster declared). These
+# do not deny a PASS — nothing was supposed to run — but they are named IN the PASS headline, so
+# "PASS" is never mistaken for "everything was verified".
+DECLARED_GAPS=()

 # --- R-TEST-03 input: the touched-requirement subset --------------------------
 # Computed ONCE here. ci/touched-requirements.sh exits 3 when it cannot establish a
@@ -64,37 +141,80 @@ rm -f "$_reason_file"
 TOUCHED=()
 [ -n "$TOUCHED_OUT" ] && mapfile -t TOUCHED <<< "$TOUCHED_OUT"
 UNDECIDED=0
+SUBSET_BROKEN=0
 if [ "$TOUCHED_RC" -eq 3 ]; then
  UNDECIDED=1
  echo >&2
  err "R-TEST-03 DECISION INPUT MISSING: the touched-requirement subset could not be"
  err "  determined (${TOUCHED_REASON:-unknown}). The scoped coverage gate did NOT run."
  summary "- **R-TEST-03 subset UNDETERMINED** (\`${TOUCHED_REASON:-unknown}\`) — the scoped coverage gate did not run."
+elif [ "$TOUCHED_RC" -ne 0 ]; then
+  # Any OTHER non-zero exit is a hard defect in the subset computation itself — an
+  # incomplete path->requirement map (a changed path matches no row) or an invalid row
+  # would report exactly this. The reasoning is taken from the unlanded
+  # fix/touched-requirements-fail-closed (47068ee): gate.sh special-cased ONLY exit 3, so
+  # any other non-zero exit left TOUCHED empty and UNDECIDED=0, and the decision below
+  # printed "MERGE GATE: PASS" having applied no coverage gate at all. Unreachable on
+  # `main` today (touched-requirements.sh exits only 0 or 3) and wired here so it is
+  # already closed the moment a fail-closed path map makes exit 1 reachable. A subset that
+  # cannot be computed is NOT an empty subset.
+  SUBSET_BROKEN=1
+  echo >&2
+  err "R-TEST-03 DECISION INPUT BROKEN: touched-requirements.sh exited ${TOUCHED_RC}"
+  err "  (${TOUCHED_REASON:-unknown}). Its output above names the paths/rows to fix."
+  summary "- **R-TEST-03 subset UNUSABLE** (\`${TOUCHED_REASON:-unknown}\`, exit ${TOUCHED_RC}) — the coverage gate could not be applied."
 elif [ "${#TOUCHED[@]}" -gt 0 ]; then
  log "touched requirements: ${TOUCHED[*]}"
 fi

 # spec-immutability (R-TEST-06): a FAIL always blocks (the spec was modified/drifted).
-# A skip means the spec repo wasn't available to verify — surfaced, not green.
+# A skip means the spec repo wasn't available to verify — UNVERIFIED, never green: it
+# denies a PASS (exit 3) and, with REQUIRE_SPEC_VERIFICATION=true, blocks outright. See the
+# file header for why this one is not upgraded to a block by CI detection alone.
 case "${OUTCOME[spec-immutability]}" in
  fail) err  "spec-immutability: FAILED -> blocks merge (R-TEST-06)"; BLOCK=1 ;;
-  skip) warn "spec-immutability: skipped (spec repo unavailable) — not verified" ;;
+  skip)
+    if truthy "$REQUIRE_SPEC_VERIFICATION"; then
+      err "spec-immutability: skipped (spec repo unavailable) and REQUIRE_SPEC_VERIFICATION=true -> blocks merge"
+      summary "- spec-immutability: **SKIPPED** (spec repo unavailable) — blocks merge (REQUIRE_SPEC_VERIFICATION=true)"
+      BLOCK=1
+    else
+      warn "spec-immutability: skipped (spec repo unavailable) — R-TEST-06 NOT VERIFIED, so"
+      warn "  this run cannot be a PASS. Check the spec repo out beside this one (or set"
+      warn "  SPEC_REPO) to verify it."
+      summary "- spec-immutability: **SKIPPED** (spec repo unavailable — R-TEST-06 not verified; not a pass)"
+      NOT_ESTABLISHED+=("spec-immutability")
+    fi ;;
  pass) ok   "spec-immutability: green" ;;
 esac

-# L0/L1 stages: any failure blocks. A SKIP here means a seam is unwired — in
-# Phase 0 that is tolerated (placeholders), but surfaced. render-golden is a
+# L0/L1 stages: any failure blocks. A SKIP here means a pinned tool is missing or a seam is
+# unwired — NEVER green. In CI (strict) that is a defect and blocks; on a workstation it
+# degrades to UNDETERMINED, which is still non-zero and still not a pass. render-golden is a
 # no-cluster reproducibility gate (canonical render == committed apps/ goldens):
 # a FAIL means a golden drifted from its ServiceDefinition source — always blocks.
 for s in lint l0 render-golden l1; do
  case "${OUTCOME[$s]}" in
    fail) err  "${s}: FAILED -> blocks merge"; BLOCK=1 ;;
-    skip) warn "${s}: skipped (unwired seam / missing tool) — not green" ;;
+    skip)
+      if strict_skips; then
+        err "${s}: skipped (unwired seam / missing tool) under STRICT skips, where the pinned"
+        err "  toolchain is installed for us (.gitea/workflows/scripts/install-tools.sh) and every"
+        err "  seam is on main — so this is a DEFECT, not an environment -> blocks merge"
+        summary "- ${s}: **SKIPPED under strict skips** (unwired seam / missing tool) — blocks merge"
+        BLOCK=1
+      else
+        warn "${s}: skipped (unwired seam / missing tool) — not green, so this run cannot be a PASS"
+        summary "- ${s}: **SKIPPED** (unwired seam / missing tool) — not green"
+        NOT_ESTABLISHED+=("$s")
+      fi ;;
    pass) ok   "${s}: green" ;;
  esac
 done

-# L2/L3 conformance: cluster-gated.
+# L2/L3 conformance: cluster-gated. The ONLY stage whose non-execution can still be a PASS,
+# because CLUSTER_AVAILABLE!=true is the environment DECLARING the capability absent rather
+# than the stage failing to run where it could have — see the file header.
 case "${OUTCOME[conformance]}" in
  fail)
    err "conformance (L2/L3): FAILED -> blocks merge"; BLOCK=1 ;;
@@ -105,18 +225,22 @@ case "${OUTCOME[conformance]}" in
      err "conformance: skipped despite CLUSTER_AVAILABLE=true -> blocks merge"; BLOCK=1
    elif [ "$UNDECIDED" -eq 1 ]; then
      warn "conformance L2/L3 UNVERIFIED, and the touched subset is unknown — nothing certified."
+      DECLARED_GAPS+=("conformance-l2-l3(no cluster declared)")
    else
      if [ "${#TOUCHED[@]}" -gt 0 ]; then
        reqs=("${TOUCHED[@]}")
        warn "conformance L2/L3 UNVERIFIED for touched requirements: ${reqs[*]}"
        warn "  (no cluster — Phase 0). These are NOT certified green."
        summary "- **UNVERIFIED (no cluster):** ${reqs[*]}"
-        if [ "$REQUIRE_CLUSTER_TESTS" = "true" ]; then
+        if truthy "$REQUIRE_CLUSTER_TESTS"; then
          err "REQUIRE_CLUSTER_TESTS=true and cluster-needing requirements are unverified -> blocks merge"
          BLOCK=1
+        else
+          DECLARED_GAPS+=("conformance-l2-l3(no cluster declared; ${#TOUCHED[@]} touched reqs unverified)")
        fi
      else
        skip "conformance L2/L3 skipped; no cluster-needing requirements touched"
+        DECLARED_GAPS+=("conformance-l2-l3(no cluster declared)")
      fi
    fi ;;
 esac
@@ -132,13 +256,34 @@ if [ "$UNDECIDED" -eq 1 ] && [ "$TOUCHED_REASON" != "on-base" ]; then
  err "cannot compute the R-TEST-03 subset (${TOUCHED_REASON:-unknown}) -> blocks merge"
  BLOCK=1
 fi
+# An incomplete/invalid path map is not an environment problem to skip past: the change under
+# gate contains paths whose requirements are UNKNOWN, so no subset can be certified.
+if [ "$SUBSET_BROKEN" -eq 1 ]; then
+  err "R-TEST-03 subset unusable (${TOUCHED_REASON:-unknown}) -> blocks merge"
+  BLOCK=1
+fi

 echo >&2
+# Precedence: BLOCKED (something is wrong) > UNDETERMINED (a stage did not run, so
+# greenness was not established) > NOT APPLICABLE (nothing to gate) > PASS. UNDETERMINED
+# outranks NOT APPLICABLE because "no branch under gate" AND "a stage did not run" is two
+# reasons this is not a green run, and the stronger, non-zero one must be the headline.
 if [ "$BLOCK" -ne 0 ]; then
  err "MERGE GATE: BLOCKED"
  summary ""
  summary "**Result: BLOCKED** — see failures above."
  exit 1
+elif [ "${#NOT_ESTABLISHED[@]}" -gt 0 ]; then
+  err "MERGE GATE: UNDETERMINED — greenness was NOT ESTABLISHED."
+  err "  Stages that did not run: ${NOT_ESTABLISHED[*]}"
+  err "  Nothing FAILED, and nothing is certified either: a stage that did not run is not"
+  err "  green (HARD RULE 4). This is exit 3, never 0 — no automation may read it as"
+  err "  merge-approved. Fix the environment (install the pinned tool / wire the seam /"
+  err "  check out the spec repo) and run again, or accept it KNOWINGLY and explicitly:"
+  err "    ./ci/gate.sh || [ \$? -eq 3 ]"
+  summary ""
+  summary "**Result: UNDETERMINED** — these stages did not run, so nothing is certified: \`${NOT_ESTABLISHED[*]}\`. Not a pass (exit 3)."
+  exit 3
 elif [ "$UNDECIDED" -eq 1 ]; then
  warn "MERGE GATE: NOT APPLICABLE — no branch under gate (${TOUCHED_REASON})."
  warn "  The stages above ran and did not fail, but NO touched-requirement subset was"
@@ -148,8 +293,16 @@ elif [ "$UNDECIDED" -eq 1 ]; then
  summary "**Result: NOT APPLICABLE** — no branch under gate (\`${TOUCHED_REASON}\`); the R-TEST-03 subset was not checked."
  exit 0
 else
-  ok "MERGE GATE: PASS (touched-requirement subset green for the layers that can run)"
-  summary ""
-  summary "**Result: PASS** — L0/L1 green. L2/L3 status per cluster availability above."
+  ok "MERGE GATE: PASS — every stage that was supposed to run RAN and was GREEN, and the"
+  ok "  R-TEST-03 touched-requirement subset was checked."
+  if [ "${#DECLARED_GAPS[@]}" -gt 0 ]; then
+    ok "  NOT verified here, because the environment DECLARED it out of scope (never a silent"
+    ok "  gap — Phase 0 by policy, see the header): ${DECLARED_GAPS[*]}"
+    summary ""
+    summary "**Result: PASS** — every stage that was supposed to run ran green. Declared out of scope (NOT verified): \`${DECLARED_GAPS[*]}\`."
+  else
+    summary ""
+    summary "**Result: PASS** — every stage that was supposed to run ran green; nothing was declared out of scope."
+  fi
  exit 0
 fi
@@ -10,6 +10,18 @@
 #   Stage 3b L0     : conformance/run.sh --layer l0 — the WHOLE-REPO L0 invariants that
 #                     a per-resource policy cannot express (secret hygiene across every
 #                     tracked file, least-privilege RBAC, spec-immutability enforcement).
+#                     Selection = the TOUCHED requirement subset (R-TEST-03) UNION every L0
+#                     test DECLARING `conformance.home.k3s/scope: whole-repo`. That union
+#                     replaces what used to be a hand-written "UNCONDITIONAL" stage per
+#                     whole-repo check (3c subst-safety / 3d keycloak-client-secrets / 3e
+#                     bulk-tier): three near-identical 12-line rationales, three hardcoded
+#                     check.sh paths and three copies of the same rc 0/3/* case block, which
+#                     did not scale and — worse — failed SILENTLY, because whoever added the
+#                     next whole-repo invariant had to REMEMBER to hand-write a stage. Now the
+#                     test declares its own scope and the runner enforces it. The reasoning and
+#                     the incidents those stages recorded were moved INTO the tests they
+#                     describe (see each chainsaw-test.yaml's `scope` annotation) and the
+#                     general mechanism is documented in conformance/lib/common.sh.
 #
 # Integration seams are env-overridable (see ci/lib.sh + README). When an owning
 # subtree is still a placeholder, this reports SKIPPED (exit 3) for that sub-stage
@@ -67,12 +79,37 @@ else
  cp -a "${KYVERNO_POLICY_DIR}/." "$l0_render/"
  find "$l0_render" -type f -name '*.yaml' -print0 \
    | xargs -0 sed -i "s/\${KYVERNO_VALIDATION_ACTION}/${KYVERNO_VALIDATION_ACTION}/g"
-  if kyverno test "$l0_render"; then
-    ok "Kyverno L0 policy tests passed"
-    summary "- kyverno-l0: **passed**"
+  # DO NOT TRUST `kyverno test`'s EXIT CODE ALONE. A policy that fails to LOAD (schema
+  # error, bad match block, malformed JMESPath) does not fail the run: every result row
+  # becomes `Skip / Invalid Policy` and the CLI still prints "N tests passed" and exits 0.
+  #
+  # MEASURED 2026-09-29 while authoring conformance-trigger-job-shape: the policy had its
+  # `subjects` in a separate `match.all` entry from its `resources` — a schema error. All 9
+  # rows came back `Skip / Invalid Policy`, and the summary read:
+  #     Test Summary: 9 tests passed and 0 tests failed
+  # `kyverno apply` on the same file reported `error: 1` and named the path. So the gate's
+  # own policy stage would have certified a SECURITY POLICY THAT DOES NOT LOAD as green.
+  #
+  # This is not specific to that policy: a typo in restrict-host-namespaces or
+  # secret-provenance would silently disable it and the gate would stay green. Scan the
+  # output for the load failure the exit code hides.
+  l0_kout="$(mktemp)"
+  if kyverno test "$l0_render" 2>&1 | tee "$l0_kout"; then
+    if grep -q 'Invalid Policy' "$l0_kout"; then
+      err "Kyverno reported 'Invalid Policy' — one or more policies FAILED TO LOAD and were"
+      err "  skipped, so their rules were never evaluated. The CLI exits 0 for this; the gate"
+      err "  must not. Run 'kyverno apply <policy> --resource <resources>' for the exact path."
+      grep -n 'Invalid Policy' "$l0_kout" | head -5 >&2
+      summary "- kyverno-l0: **FAILED — policy did not load** (Invalid Policy; rules never evaluated)"
+      rc=1
+    else
+      ok "Kyverno L0 policy tests passed"
+      summary "- kyverno-l0: **passed**"
+    fi
  else
    err "Kyverno L0 policy tests failed"; summary "- kyverno-l0: **FAILED**"; rc=1
  fi
+  rm -f "$l0_kout"
  rm -rf "$l0_render"
 fi

@@ -83,134 +120,45 @@ fi
 # binding, the spec-immutability gate's own behaviour) live in the conformance
 # harness's tests/l0-static subtree and run with no cluster. This stage executes them
 # through the same single-command runner CI and a laptop both use (R-TEST-02).
-log "Stage: L0 static conformance checks (${CONFORMANCE_CMD} --layer l0)"
+#
+# THE UNION, AND WHY IT IS NOT OPTIONAL (R-TEST-03's blind spot)
+# --------------------------------------------------------------
+# 3b scopes the conformance run to the TOUCHED requirements. That is right for an invariant
+# whose inputs live under the subtree its requirements map to. It is WRONG for one that
+# quantifies over the WHOLE tracked tree, or over subtrees (apps/, infra/, most of platform/)
+# that ci/touched-requirements.sh's coarse path map keys to NOTHING: for those, the change
+# most likely to break the invariant attributes no requirement at all, so requirement-scoped
+# selection filters the check out of EXACTLY that change. `--include-scope whole-repo` unions
+# in every L0 test that DECLARES that scope, so those run on every gate invocation.
+#
+# rc 3 IS NOT A PASS. The runner returns 3 when a scope-declared check SKIPPED (its subject
+# subtree is absent, or it has no check script): UNWIRED, not green, exactly as the deleted
+# per-check stages had it ("check SKIPPED (clusters/ absent) — not a pass"). It is mapped to
+# the gate's own rc 3 below, never to rc 0.
+: "${WHOLE_REPO_SCOPE:=whole-repo}"
+log "Stage: L0 static conformance checks (${CONFORMANCE_CMD} --layer l0 --include-scope ${WHOLE_REPO_SCOPE})"
 if ! entrypoint_ready "$CONFORMANCE_CMD"; then
  skip "conformance runner not present at '${CONFORMANCE_CMD}' — UNWIRED, not green"
  summary "- l0-static: **SKIPPED** (conformance runner missing)"
  if [ "$rc" -eq 0 ]; then rc=3; fi
 else
  load_touched_requirements
-  if "$CONFORMANCE_CMD" --layer l0 ${REQ_ARGS[@]+"${REQ_ARGS[@]}"}; then
-    ok "L0 static conformance checks passed"
-    summary "- l0-static: **passed**"
-  else
-    err "L0 static conformance checks failed"
-    summary "- l0-static: **FAILED**"
-    rc=1
-  fi
-fi
-
-# ---- Stage 3c: Flux post-build substitution safety (UNCONDITIONAL) ----------
-# R-ENV-02's promote-once mechanism is `postBuild.substituteFrom cluster-vars`, and it
-# FAILS OPEN: an undefined ${TOKEN} becomes the empty string and the Kustomization still
-# reports Ready. That emptied Cilium's k8sServiceHost and broke the CNI on 2/3 dev nodes
-# (DECISIONS-LOG 2026-09-01, "substitution race that fails OPEN"). The check asserts every
-# ${...} in every substituted path is DEFINED in cluster-vars or deliberately ESCAPED
-# `$${...}` — i.e. that enabling the StrictPostBuildSubstitutions feature gate cannot fail
-# a legitimate manifest, and that no expansion silently empties today.
-#
-# WHY THIS IS ITS OWN STAGE and not left to Stage 3b: 3b scopes the conformance run to the
-# TOUCHED requirements (R-TEST-03), and ci/touched-requirements.sh's coarse path map keys
-# only clusters/* to R-ENV-02 — an edit to a SUBSTITUTED manifest under apps/ or platform/
-# attributes no requirement, so the requirement-scoped selection would filter this check
-# out of exactly the change that introduces the bug. The invariant is whole-repo (same
-# reasoning as spec-immutability's own gate stage), so it runs on EVERY gate invocation.
-# When 3b's touched set does include R-ENV-02/R-GITOPS-01 the check runs twice; it is a
-# sub-second offline scan with no side effects, so the duplication is not worth avoiding.
-SUBST_CHECK="${SUBST_CHECK:-${REPO_ROOT}/conformance/tests/l0-static/flux-postbuild-substitution/check.sh}"
-log "Stage: Flux postBuild substitution safety (${SUBST_CHECK})"
-if [ ! -f "$SUBST_CHECK" ]; then
-  skip "substitution check not present at '${SUBST_CHECK}' — UNWIRED, not green"
-  summary "- subst-safety: **SKIPPED** (check missing)"
-  if [ "$rc" -eq 0 ]; then rc=3; fi
-else
-  subst_rc=0
-  bash "$SUBST_CHECK" || subst_rc=$?
-  case "$subst_rc" in
-    0) ok "Flux postBuild substitution safety passed"
-       summary "- subst-safety: **passed**" ;;
-    3) skip "substitution check SKIPPED (clusters/ absent) — not a pass"
-       summary "- subst-safety: **SKIPPED** (nothing to audit)"
+  l0_static_rc=0
+  "$CONFORMANCE_CMD" --layer l0 --include-scope "$WHOLE_REPO_SCOPE" \
+    ${REQ_ARGS[@]+"${REQ_ARGS[@]}"} || l0_static_rc=$?
+  case "$l0_static_rc" in
+    0) ok "L0 static conformance checks passed"
+       summary "- l0-static: **passed**" ;;
+    3) skip "an L0 check declaring scope='${WHOLE_REPO_SCOPE}' SKIPPED — UNWIRED, not a pass"
+       summary "- l0-static: **SKIPPED** (a whole-repo check is UNWIRED — not a pass)"
       if [ "$rc" -eq 0 ]; then rc=3; fi ;;
-    *) err "Flux postBuild substitution safety FAILED"
-       summary "- subst-safety: **FAILED**"; rc=1 ;;
-  esac
-fi
-
-# ---- Stage 3d: Keycloak client-secret declaration + reconciler (UNCONDITIONAL) ----
-# The Keycloak realm import resolves each OIDC client's secret from an `(env:NAME)`
-# placeholder. When the operator cannot resolve one it stores the LITERAL placeholder as
-# the client secret AND THE IMPORT JOB STILL REPORTS SUCCESS, then rests at Done=True and
-# never re-runs. On 2026-09-06 that had all 12 prod clients unusable ("Invalid client or
-# Invalid client credentials") behind an entirely green cluster; dev had one. The check
-# asserts the declaration is self-consistent (every placeholder defined, every Secret key
-# present, names matching the reconciler's contract), that the Flux ordering is a REAL
-# dependsOn edge rather than a comment, and — by extracting the shipped script from its
-# ConfigMap and running its --selftest — that the reconciler is compare-then-write,
-# idempotent, non-logging and blast-radius-bounded.
-#
-# WHY ITS OWN UNCONDITIONAL STAGE, same reasoning as 3c: Stage 3b scopes the conformance
-# run to the TOUCHED requirements (R-TEST-03). This check's invariant spans platform/,
-# platform-config/ and clusters/, so a change that breaks it need not attribute R-IDP-03/04
-# and the requirement-scoped selection would filter it out of exactly the change that
-# introduces the bug. It is a sub-second offline scan plus a loopback selftest, with no
-# side effects, so running it twice when 3b also selects it is not worth avoiding.
-KEYCLOAK_SECRET_CHECK="${KEYCLOAK_SECRET_CHECK:-${REPO_ROOT}/conformance/tests/l0-static/keycloak-client-secret-reconciler/check.sh}"
-log "Stage: Keycloak client-secret reconciler safety (${KEYCLOAK_SECRET_CHECK})"
-if [ ! -f "$KEYCLOAK_SECRET_CHECK" ]; then
-  skip "keycloak client-secret check not present at '${KEYCLOAK_SECRET_CHECK}' — UNWIRED, not green"
-  summary "- keycloak-client-secrets: **SKIPPED** (check missing)"
-  if [ "$rc" -eq 0 ]; then rc=3; fi
-else
-  kc_rc=0
-  bash "$KEYCLOAK_SECRET_CHECK" || kc_rc=$?
-  case "$kc_rc" in
-    0) ok "Keycloak client-secret declaration + reconciler passed"
-       summary "- keycloak-client-secrets: **passed**" ;;
-    3) skip "keycloak client-secret check SKIPPED (platform/keycloak absent) — not a pass"
-       summary "- keycloak-client-secrets: **SKIPPED** (nothing to audit)"
-       if [ "$rc" -eq 0 ]; then rc=3; fi ;;
-    *) err "Keycloak client-secret declaration + reconciler FAILED"
-       summary "- keycloak-client-secrets: **FAILED**"; rc=1 ;;
-  esac
-fi
-
-# ---- Stage 3e: bulk tier distinct from the replicated tier (UNCONDITIONAL) ----
-# The `bulk` StorageClass sat as a REPLACE-ME stub for six roadmap phases, and the only
-# thing keeping a multi-terabyte media library off the 3-replica `longhorn` class was four
-# hand-written comments in ServiceDefinitions. A bulk volume that lands on the replicated
-# tier does not fail loudly — Longhorn accepts the PVC and starts replicating 3x of data
-# three mini-PCs cannot hold. The check asserts the tier separation, that a bulk volume is
-# statically pre-bound from BOTH ends (so nothing can dynamically provision an EMPTY
-# stand-in that mounts and Binds perfectly while the real data is never attached), Retain,
-# hard/NFSv4 mount options, the read-only coupling between PV and volumeMount, that no
-# workload mounts one export twice (which breaks Sonarr/Radarr hardlinks with EXDEV), and
-# that the server is a per-environment knob every overlay supplies.
-#
-# WHY ITS OWN UNCONDITIONAL STAGE, same reasoning as 3c/3d: Stage 3b scopes the conformance
-# run to the TOUCHED requirements (R-TEST-03), and ci/touched-requirements.sh's path map
-# keys NEITHER apps/* nor platform/longhorn/* to the bulk requirement. So the change most
-# likely to break this — moving a bulk volume onto the replicated tier, or narrowing one
-# export into two mounts — could attribute no requirement at all and be gated by nothing.
-# The invariant spans catalog/, apps/ and clusters/, so it runs on EVERY gate invocation.
-BULK_TIER_CHECK="${BULK_TIER_CHECK:-${REPO_ROOT}/conformance/tests/l0-static/bulk-tier-distinct-from-replicated/check.sh}"
-log "Stage: bulk tier distinct from replicated tier (${BULK_TIER_CHECK})"
-if [ ! -f "$BULK_TIER_CHECK" ]; then
-  skip "bulk tier check not present at '${BULK_TIER_CHECK}' — UNWIRED, not green"
-  summary "- bulk-tier: **SKIPPED** (check missing)"
-  if [ "$rc" -eq 0 ]; then rc=3; fi
-else
-  bulk_rc=0
-  bash "$BULK_TIER_CHECK" || bulk_rc=$?
-  case "$bulk_rc" in
-    0) ok "Bulk tier distinctness + static binding passed"
-       summary "- bulk-tier: **passed**" ;;
-    3) skip "bulk tier check SKIPPED (catalog/ or apps/ absent) — not a pass"
-       summary "- bulk-tier: **SKIPPED** (nothing to audit)"
-       if [ "$rc" -eq 0 ]; then rc=3; fi ;;
-    *) err "Bulk tier distinctness + static binding FAILED"
-       summary "- bulk-tier: **FAILED**"; rc=1 ;;
+    *) err "L0 static conformance checks failed"
+       summary "- l0-static: **FAILED**"
+       rc=1 ;;
  esac
+  # Per-check step-summary lines, so the gate output still NAMES what ran — the generated
+  # replacement for the one hardcoded `summary` line each deleted stage carried.
+  emit_offline_summary
 fi

 case "$rc" in
@@ -29,7 +29,18 @@ req_args=(${REQ_ARGS[@]+"${REQ_ARGS[@]}"})
 # [--requirements R-A,R-B]; it ALWAYS writes artifacts to a FIXED location
 # (conformance/_artifacts/) and does NOT accept --junit/--coverage. Invoke by layer +
 # touched subset, then COLLECT its artifacts into the CI artifact dirs.
-"$CONFORMANCE_CMD" --layer l1 ${req_args[@]+"${req_args[@]}"}
+# --include-scope: union the touched subset with every L1 test DECLARING
+# `conformance.home.k3s/scope: whole-repo`. As of 2026-09-18 ALL THREE L1 tests declare it, so this
+# is load-bearing rather than a no-op: every L1 golden is checked on every gate run, whatever the
+# touched paths attribute. It was wired HERE first, ahead of any declaration, so picking up a new
+# whole-repo invariant needs only the annotation instead of someone remembering to hand-write a
+# stage — and that "someone must remember" is exactly how the 2026-09-04 external-dns merge gated
+# GREEN while leaving all three goldens stale (see the rationale in the Tests themselves).
+# rc 3 = a scope-declared check SKIPPED = UNWIRED, never a pass.
+: "${WHOLE_REPO_SCOPE:=whole-repo}"
+l1_rc=0
+"$CONFORMANCE_CMD" --layer l1 --include-scope "$WHOLE_REPO_SCOPE" \
+  ${req_args[@]+"${req_args[@]}"} || l1_rc=$?

 CONF_ART="$(dirname "$CONFORMANCE_CMD")/_artifacts"
 if [ -f "${CONF_ART}/report.junit.xml" ]; then
@@ -39,5 +50,16 @@ if [ -d "${CONF_ART}/coverage" ]; then
  cp -r "${CONF_ART}/coverage/." "${COVERAGE_DIR}/"
 fi

-ok "L1 rendering checks passed"
-summary "- l1-render: **passed**"
+case "$l1_rc" in
+  0) ok "L1 rendering checks passed"
+     summary "- l1-render: **passed**"
+     emit_offline_summary ;;
+  3) skip "an L1 check declaring scope='${WHOLE_REPO_SCOPE}' SKIPPED — UNWIRED, not a pass"
+     summary "- l1-render: **SKIPPED** (a whole-repo check is UNWIRED — not a pass)"
+     emit_offline_summary
+     exit 3 ;;
+  *) err "L1 rendering checks FAILED (rc=${l1_rc})"
+     summary "- l1-render: **FAILED**"
+     emit_offline_summary
+     exit "$l1_rc" ;;
+esac
@@ -72,20 +72,83 @@ entrypoint_ready() {
  return 1
 }

-# --- Cluster detection (drives SKIP vs run for L2/L3) -------------------------
-# A cluster is 'available' only if explicitly declared. We NEVER auto-assume a
-# cluster in Phase 0 — silence means SKIP, not pass (HARD RULE 4).
-#   CLUSTER_AVAILABLE=true   -> L2/L3 run and are REQUIRED green
-#   CLUSTER_AVAILABLE=false/unset -> L2/L3 SKIP (reported, never faked green)
-cluster_available() {
-  case "${CLUSTER_AVAILABLE:-false}" in
-    true|1|yes) return 0 ;;
+# truthy <value> — the ONE place the repo's "is this switch on" spelling lives, so
+# CLUSTER_AVAILABLE / REQUIRE_CLUSTER_TESTS / REQUIRE_SPEC_VERIFICATION / GATE_STRICT_SKIPS
+# all agree. Anything not listed is OFF, and that direction matters: a misspelled value
+# (CLUSTER_AVAILABLE=ture, REQUIRE_SPEC_VERIFICATION=yeah) leaves the guard OFF rather than
+# silently declaring a capability "available", so a typo can only make the gate stricter about
+# what it claims to have verified, never looser.
+truthy() {
+  case "${1:-}" in
+    true|TRUE|True|1|yes|YES|y|on|ON) return 0 ;;
    *) return 1 ;;
  esac
 }

+# --- Cluster detection (drives SKIP vs run for L2/L3) -------------------------
+# A cluster is 'available' only if explicitly DECLARED. We NEVER auto-assume a
+# cluster in Phase 0 — silence means SKIP, not pass (HARD RULE 4).
+#   CLUSTER_AVAILABLE=true   -> L2/L3 run and are REQUIRED green
+#   CLUSTER_AVAILABLE=false/unset -> L2/L3 SKIP (reported, never faked green)
+# That DECLARATION is what makes an L2/L3 skip different IN KIND from every other skip —
+# see "WHICH SKIPS BLOCK, AND WHY" in ci/gate.sh.
+cluster_available() { truthy "${CLUSTER_AVAILABLE:-false}"; }
+
+# --- Skip strictness: is this a CI runner, or a workstation? -------------------
+# A SKIPPED stage is never green anywhere (HARD RULE 4), but its SEVERITY differs:
+#
+#   CI       the pinned toolchain is installed by .gitea/workflows/scripts/install-tools.sh
+#            before the gate runs, and every seam is on `main`. A stage that skips here is a
+#            DEFECT (a tool dropped from the installer, a seam that went unwired) -> BLOCK.
+#   local    a missing pinned tool is a real, ordinary local condition -> the gate reports
+#            UNDETERMINED (exit 3): not green, not a pass, but distinguishable from a red.
+#
+# HOW STRICTNESS IS DECIDED — DECLARED first, detected only as a fallback:
+#
+#   1. GATE_STRICT_SKIPS=true|false is the AUTHORITY. .gitea/workflows/gate.yml sets `true` on
+#      the gate step, so on the one CI runner that matters strictness is a DECLARATION IN THE
+#      WORKFLOW, not an inference: the environment that KNOWS it is CI says so, and no
+#      env-var sniffing can get it wrong.
+#   2. `auto` (the default — anywhere the caller said nothing) falls back to GITHUB_ACTIONS /
+#      CI, which are set by the runner ITSELF (Gitea's act_runner, as well as GitHub). We do
+#      NOT sniff hostnames, paths or tool availability: a heuristic that guesses "this looks
+#      like CI" is exactly the unreliable inference this gate must not contain.
+#
+# WHY A WRONG ANSWER CANNOT FAIL OPEN: both branches are non-zero and NEITHER is a pass. A CI
+# run misread as local yields UNDETERMINED (exit 3) instead of BLOCKED (exit 1) — that still
+# fails the job unless its caller explicitly tolerates 3, which gate.yml does only knowingly
+# and only for the one declared-environmental skip (see its comment). A workstation misread as
+# CI yields BLOCKED instead of UNDETERMINED — harsher, never looser. Set GATE_STRICT_SKIPS=true
+# locally to rehearse CI strictness.
+: "${GATE_STRICT_SKIPS:=auto}"
+strict_skips() {
+  case "$GATE_STRICT_SKIPS" in
+    auto) truthy "${GITHUB_ACTIONS:-}" || truthy "${CI:-}" ;;
+    *)    truthy "$GATE_STRICT_SKIPS" ;;
+  esac
+}
+
 mkartifacts() { mkdir -p "$JUNIT_DIR" "$COVERAGE_DIR"; }

+# --- Offline (L0/L1) per-check step summary -----------------------------------
+# conformance/lib/run_l1_offline.py writes one Markdown line per check it executed to
+# conformance/_artifacts/offline-summary.md. Splice those into $GITHUB_STEP_SUMMARY so the
+# gate's output still NAMES every check that ran and its verdict.
+#
+# WHY THIS EXISTS: ci/l0.sh used to carry a hand-written stage per whole-repo check, each with
+# its own `summary "- subst-safety: **passed**"` line. Those stages are gone (the tests declare
+# `conformance.home.k3s/scope: whole-repo` instead and the runner unions them in), so the
+# naming is generated for EVERY offline check rather than for the three that had a stage.
+: "${OFFLINE_SUMMARY_FILE:=${CONFORMANCE_DIR}/_artifacts/offline-summary.md}"
+emit_offline_summary() {
+  local f="${1:-$OFFLINE_SUMMARY_FILE}" line
+  [ -f "$f" ] || return 0
+  while IFS= read -r line; do
+    [ -n "$line" ] && summary "  $line"
+  done < "$f"
+  return 0
+}
+
 # --- Touched-requirement subset (R-TEST-03 input) ----------------------------
 # Sets: TOUCHED_RC (0 ok / 3 not determinable), TOUCHED_REQS[] and REQ_ARGS[]
 # (ready to splice into a conformance/run.sh invocation).
@@ -111,7 +174,16 @@ load_touched_requirements() {
    warn "  Running the FULL layer as a superset sanity net; the SCOPED R-TEST-03"
    warn "  coverage check is NOT performed here — ci/gate.sh reports that as UNDECIDED."
  elif [ "$rc" -ne 0 ]; then
-    warn "touched-requirements.sh exited ${rc}; proceeding with the full layer."
+    # Any OTHER non-zero exit means the subset is UNUSABLE, not empty (today: a
+    # path->requirement map that cannot classify a changed path, once that map fails closed).
+    # The FULL layer still runs here as a superset — nothing goes untested — but this stage must
+    # not claim the SCOPED check happened, and ci/gate.sh turns the same exit into a BLOCKED
+    # merge decision. Wording carried over from the unlanded fix/touched-requirements-fail-closed
+    # (47068ee), whose gate-side half this branch lands.
+    warn "touched-requirements.sh exited ${rc} (subset UNUSABLE — see its output above)."
+    warn "  Running the FULL layer as a superset; the SCOPED R-TEST-03 check did NOT happen."
+    warn "  ci/gate.sh BLOCKS the merge on this: fix the path->requirement map in"
+    warn "  ci/touched-requirements.sh so every changed path is classified."
  elif [ "${#TOUCHED_REQS[@]}" -gt 0 ]; then
    log "touched requirements: ${TOUCHED_REQS[*]}"
    REQ_ARGS=(--requirements "$(IFS=,; echo "${TOUCHED_REQS[*]}")")
@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+# =============================================================================
+# ci/render-keycloak-client-urls.py
+#
+# Render platform/keycloak/client-urls.yaml FROM platform/keycloak/keycloak-realm-import.yaml.
+#
+# WHY THIS EXISTS
+# ---------------
+# The Keycloak realm import is a ONE-SHOT that fails OPEN: once it rests at
+# Done=True / Started=False it never re-runs, so a redirect URI changed in git is
+# never applied to the realm. The client-secret half of that failure class is
+# already healed by a level-triggered CronJob (platform/keycloak/client-secret-
+# reconciler.yaml). This renderer supplies the DESIRED STATE that the same CronJob
+# needs to heal the URL half.
+#
+# THE CONSTRAINT THAT SHAPES IT: the reconciler pod runs with
+# automountServiceAccountToken: false. It has NO Kubernetes API access at all, by
+# design (R-SEC-02) — so it cannot read the KeycloakRealmImport CR to learn what
+# the realm is supposed to look like. Its inputs must be MOUNTED. Hence a
+# ConfigMap.
+#
+# A hand-authored ConfigMap would be a SECOND SOURCE OF TRUTH for every public
+# hostname in the realm, free to disagree with the realm import — and "two
+# declarations that can disagree" is the same shape as the bug this whole effort
+# is closing. So the ConfigMap is GENERATED from the realm import and the
+# generation is GATED: conformance/tests/l0-static/keycloak-client-secret-
+# reconciler/check.sh runs this script with --check on every merge, and the merge
+# fails if the committed file is not what this renderer produces. That is the same
+# render==golden idiom catalog/render.py + ci/render-golden.sh already use for
+# apps/.
+#
+# STRINGS ARE COPIED VERBATIM, NEVER RE-DERIVED. If a URL in the realm import is
+# written as a Flux substitution token (https://grafana.${BASE_DOMAIN}/...), the
+# token is carried through into the ConfigMap CHARACTER FOR CHARACTER. Both files
+# are rendered by the SAME Flux Kustomization (./platform-config, whose
+# postBuild.substituteFrom reads cluster-vars), so both are substituted in the
+# same pass with the same values and cannot disagree about what BASE_DOMAIN is.
+# This renderer never parses, splits, or reconstructs a hostname, and never reads
+# cluster-vars — so there is no second place for the domain to be decided.
+#
+# USAGE
+#   python3 ci/render-keycloak-client-urls.py            # print the rendered file
+#   python3 ci/render-keycloak-client-urls.py --write     # write it (regenerate)
+#   python3 ci/render-keycloak-client-urls.py --check      # exit 1 if it has drifted
+# =============================================================================
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    print("FATAL: PyYAML is required (same dependency as catalog/render.py)",
+          file=sys.stderr)
+    raise SystemExit(1)
+
+ROOT = Path(__file__).resolve().parent.parent
+IMPORT_FILE = "platform/keycloak/keycloak-realm-import.yaml"
+OUT_FILE = "platform/keycloak/client-urls.yaml"
+DATA_KEY = "client-urls.json"
+CONFIGMAP_NAME = "keycloak-client-urls"
+NAMESPACE = "keycloak"
+
+# The client fields this renderer exports, and therefore the ONLY fields the
+# reconciler may write. Every one of them is an environment-derived URL: it changes
+# when BASE_DOMAIN changes, and a stale value breaks OIDC login (a wrong
+# redirectUri) or silently widens trust (a stale wildcard left behind).
+#
+# DELIBERATELY ABSENT: `secret` (healed by the secret pass from the SOPS Secret,
+# and it must never appear in a ConfigMap), and every non-URL field —
+# protocolMappers, defaultClientScopes, attributes, flags. Those are not
+# environment-derived, so nothing re-renders them on a domain flip; keeping them
+# out keeps the reconciler's write surface as narrow as the problem.
+LIST_FIELDS = ("redirectUris", "webOrigins")
+STR_FIELDS = ("rootUrl", "baseUrl", "adminUrl")
+
+
+def render(root: Path) -> str:
+    """Return the full text of client-urls.yaml as it should be committed."""
+    docs = list(yaml.safe_load_all((root / IMPORT_FILE).read_text()))
+    imp = next((d for d in docs if d and d.get("kind") == "KeycloakRealmImport"), None)
+    if imp is None:
+        raise SystemExit("FATAL: no KeycloakRealmImport document in %s" % IMPORT_FILE)
+    clients = (imp.get("spec") or {}).get("realm", {}).get("clients") or []
+    if not clients:
+        # Fail closed. Emitting an empty desired state would make the reconciler
+        # believe every client is unmanaged and silently stop reconciling URLs.
+        raise SystemExit("FATAL: %s declares zero clients — refusing to render an "
+                         "empty desired state" % IMPORT_FILE)
+
+    want: dict[str, dict] = {}
+    for c in clients:
+        cid = c.get("clientId")
+        if not isinstance(cid, str) or not cid:
+            raise SystemExit("FATAL: %s has a client with no clientId" % IMPORT_FILE)
+        entry: dict[str, object] = {}
+        for f in LIST_FIELDS:
+            if f not in c:
+                continue                 # not declared => NOT MANAGED (never forced empty)
+            v = c[f]
+            if not isinstance(v, list) or not all(isinstance(x, str) for x in v):
+                raise SystemExit("FATAL: %s client %r field %s is not a list of strings"
+                                 % (IMPORT_FILE, cid, f))
+            entry[f] = list(v)           # verbatim, order as authored
+        for f in STR_FIELDS:
+            if f not in c:
+                continue
+            v = c[f]
+            if not isinstance(v, str):
+                raise SystemExit("FATAL: %s client %r field %s is not a string"
+                                 % (IMPORT_FILE, cid, f))
+            entry[f] = v
+        if entry:
+            want[cid] = entry
+    if not want:
+        raise SystemExit("FATAL: no client in %s declares any of %s — refusing to render "
+                         "an empty desired state"
+                         % (IMPORT_FILE, ", ".join(LIST_FIELDS + STR_FIELDS)))
+
+    body = json.dumps(want, indent=2, sort_keys=True, ensure_ascii=False)
+    indented = "\n".join(("    " + ln) if ln else "" for ln in body.splitlines())
+    return HEADER + indented + "\n"
+
+
+HEADER = """---
+# =============================================================================
+# GENERATED FILE — DO NOT EDIT BY HAND.
+#
+#   source:      platform/keycloak/keycloak-realm-import.yaml (spec.realm.clients)
+#   regenerate:  python3 ci/render-keycloak-client-urls.py --write
+#   gated by:    conformance/tests/l0-static/keycloak-client-secret-reconciler
+#                (runs this renderer with --check on every merge)
+#
+# WHAT THIS IS: the DESIRED STATE for every environment-derived client URL in the
+# `homelab` realm — redirectUris, webOrigins, rootUrl, baseUrl, adminUrl. The
+# client-secret reconciler CronJob mounts it and makes the live realm match it.
+#
+# WHY IT IS A SEPARATE OBJECT: the realm import is a ONE-SHOT that never re-runs
+# once Done=True, so a redirect URI edited in git never reaches the realm. Prod's
+# stored redirect URIs were measured still pointing at the pre-migration hostname
+# while git declared the new one, and every OIDC login would have failed with a
+# redirect_uri mismatch. The reconciler is the level-triggered loop that closes
+# that; this file is what it reconciles TOWARDS.
+#
+# WHY IT IS GENERATED AND NOT AUTHORED: a hand-written copy of every public
+# hostname would be a second source of truth, free to disagree with the realm
+# import. It is rendered from the import and the render is gated, so the two
+# cannot drift. URL strings are copied VERBATIM — if the source uses a
+# ${BASE_DOMAIN} token it appears here unchanged, and both files are substituted
+# by the SAME Flux Kustomization (./platform-config), so the domain is decided in
+# exactly one place.
+#
+# A field that is NOT declared on a client in the realm import is simply ABSENT
+# here, and the reconciler leaves it alone. Absence means UNMANAGED, never
+# "force to empty".
+# =============================================================================
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: %s
+  namespace: %s
+  labels:
+    app.kubernetes.io/name: %s
+    app.kubernetes.io/part-of: keycloak
+data:
+  %s: |
+""" % (CONFIGMAP_NAME, NAMESPACE, CONFIGMAP_NAME, DATA_KEY)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    g = ap.add_mutually_exclusive_group()
+    g.add_argument("--write", action="store_true", help="write %s" % OUT_FILE)
+    g.add_argument("--check", action="store_true",
+                   help="exit 1 if the committed file has drifted from the source")
+    args = ap.parse_args()
+
+    want = render(ROOT)
+    target = ROOT / OUT_FILE
+
+    if args.write:
+        target.write_text(want, encoding="utf-8")
+        print("wrote %s" % OUT_FILE)
+        return 0
+
+    if args.check:
+        if not target.is_file():
+            print("CHECK FAIL: %s does not exist. Run: python3 "
+                  "ci/render-keycloak-client-urls.py --write" % OUT_FILE, file=sys.stderr)
+            return 1
+        have = target.read_text(encoding="utf-8")
+        if have == want:
+            print("client-urls.yaml is in sync with %s" % IMPORT_FILE)
+            return 0
+        print("CHECK FAIL: %s has DRIFTED from %s — the reconciler would converge the "
+              "realm on a desired state the realm import does not declare.\n"
+              "Regenerate with: python3 ci/render-keycloak-client-urls.py --write\n"
+              % (OUT_FILE, IMPORT_FILE), file=sys.stderr)
+        for line in difflib.unified_diff(have.splitlines(True), want.splitlines(True),
+                                         fromfile="committed " + OUT_FILE,
+                                         tofile="rendered from " + IMPORT_FILE):
+            sys.stderr.write(line)
+        return 1
+
+    sys.stdout.write(want)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+# ci/tests/gate-decision.test.sh — the merge gate's OWN decision table.
+#
+# WHY THIS SUITE EXISTS (2026-09-13). ci/gate.sh used to set BLOCK=1 for a FAILED stage but
+# only `warn` for a SKIPPED one, so it printed the words "— not green" and then concluded
+# `MERGE GATE: PASS` and exited 0. Observed live twice: `prom-rules` skipped for a missing
+# promtool, and `l0` skipped for a missing pinned kyverno CLI — both read by automation as
+# merge-approved. That is fail-open in the one component whose entire job is to fail closed,
+# and nothing tested it: every other ci/tests suite covers the INPUT (touched-requirements),
+# none covered the DECISION.
+#
+# WHAT IS UNDER TEST: the real ci/gate.sh and ci/lib.sh, copied into a throwaway CI_DIR beside
+# STUB stage scripts whose exit codes this suite dictates (STAGE_RC_<stage>) and a stub
+# touched-requirements.sh whose rc/reason it dictates (TR_RC / TR_REASON / TR_OUT). Stubbing the
+# stages is the point: this asserts how the gate REASONS about pass/fail/skip, independently of
+# what any stage happens to do on this machine — so it runs anywhere, with no tools, no cluster,
+# no network, in milliseconds.
+#
+# THE INVARIANT: `MERGE GATE: PASS` + exit 0 means every stage that was supposed to run RAN and
+# was GREEN. A stage that could not run is never a pass, and the exit code says so too.
+#
+# Run:  ci/tests/gate-decision.test.sh     (or `make -C ci test`)
+set -uo pipefail
+
+REAL_CI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+PASS=0 FAIL=0
+ok()  { printf '  ok   %s\n' "$*"; PASS=$((PASS+1)); }
+bad() { printf '  FAIL %s\n' "$*"; FAIL=$((FAIL+1)); }
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+CI="${TMP}/ci"; mkdir -p "$CI"
+REPO="${TMP}/repo"; mkdir -p "$REPO"
+
+cp "${REAL_CI_DIR}/gate.sh" "${REAL_CI_DIR}/lib.sh" "${REAL_CI_DIR}/versions.env" "$CI/"
+
+# One stub per stage. It exits with STAGE_RC_<stage-with-dashes-as-underscores>, default 0.
+for stage in spec-immutability lint l0 render-golden l1 conformance; do
+  cat > "${CI}/${stage}.sh" <<'STUB'
+#!/usr/bin/env bash
+n="$(basename "$0" .sh)"; v="STAGE_RC_${n//-/_}"
+exit "${!v:-0}"
+STUB
+  chmod +x "${CI}/${stage}.sh"
+done
+
+# Stub decision input. TR_RC (default 0), TR_REASON (written to $TOUCHED_REASON_FILE like the
+# real script does), TR_OUT (the touched requirement list on stdout).
+cat > "${CI}/touched-requirements.sh" <<'STUB'
+#!/usr/bin/env bash
+if [ -n "${TOUCHED_REASON_FILE:-}" ]; then printf '%s\n' "${TR_REASON:-}" > "$TOUCHED_REASON_FILE"; fi
+[ -n "${TR_OUT:-}" ] && printf '%s\n' "$TR_OUT"
+exit "${TR_RC:-0}"
+STUB
+chmod +x "${CI}/touched-requirements.sh"
+
+# run_gate <VAR=VAL>... — run the gate with a clean, explicit environment. Sets OUT and RC.
+# GATE_STRICT_SKIPS is pinned false unless a case says otherwise, so the suite never depends on
+# whether the machine running it happens to look like CI.
+OUT="" RC=0
+run_gate() {
+  local summary_file="${TMP}/summary.md"; : > "$summary_file"
+  OUT="$(env -i PATH="$PATH" HOME="$HOME" \
+        REPO_ROOT="$REPO" GITHUB_STEP_SUMMARY="$summary_file" \
+        GATE_STRICT_SKIPS=false TR_OUT="R-TEST-03" \
+        "$@" bash "${CI}/gate.sh" 2>&1)"
+  RC=$?
+  SUMMARY="$(cat "$summary_file")"
+}
+
+# assert_verdict <headline> <expected-rc> <label>
+assert_verdict() {
+  local want="$1" want_rc="$2" label="$3"
+  if ! grep -qF "MERGE GATE: ${want}" <<<"$OUT"; then
+    bad "${label}: headline should be '${want}' — got: $(grep -oE 'MERGE GATE: [A-Z ]+' <<<"$OUT" | tail -1)"
+  elif [ "$RC" -ne "$want_rc" ]; then
+    bad "${label}: headline '${want}' correct but exit code ${RC} != ${want_rc}"
+  else
+    ok "${label} -> ${want}, exit ${want_rc}"
+  fi
+}
+# The load-bearing negative: nothing may say PASS, and nothing may exit 0.
+assert_not_pass() {
+  local label="$1"
+  if grep -qF "MERGE GATE: PASS" <<<"$OUT"; then bad "${label}: printed 'MERGE GATE: PASS'"
+  elif [ "$RC" -eq 0 ]; then bad "${label}: exited 0"
+  else ok "${label}: not a PASS, non-zero exit (${RC})"; fi
+}
+
+echo "== 1. the happy path: every stage green"
+run_gate
+assert_verdict PASS 0 "all stages green + a touched subset"
+grep -qF "nothing was declared out of scope" <<<"$SUMMARY" \
+  && ok "PASS summary states nothing was declared out of scope" \
+  || bad "PASS summary does not state the absence of declared gaps"
+
+echo
+echo "== 2. a FAILED stage blocks (unchanged behaviour, locked down)"
+for s in lint l0 render-golden l1 conformance spec-immutability; do
+  run_gate "STAGE_RC_${s//-/_}=1"
+  assert_verdict BLOCKED 1 "${s} FAILED"
+done
+
+echo
+echo "== 3. THE REGRESSION: a SKIPPED stage is not a PASS and not exit 0"
+for s in lint l0 render-golden l1; do
+  run_gate "STAGE_RC_${s//-/_}=3"
+  assert_not_pass "${s} SKIPPED (local)"
+  assert_verdict UNDETERMINED 3 "${s} SKIPPED (local)"
+  grep -qF "$s" <<<"$SUMMARY" && ok "${s}: the step summary names the stage that did not run" \
+                              || bad "${s}: step summary does not name the skipped stage"
+done
+
+echo
+echo "== 4. under STRICT skips (CI declares it) a could-not-run skip BLOCKS, never merely 3"
+for s in lint l0 render-golden l1; do
+  run_gate GATE_STRICT_SKIPS=true "STAGE_RC_${s//-/_}=3"
+  assert_verdict BLOCKED 1 "${s} SKIPPED with GATE_STRICT_SKIPS=true"
+done
+# ...which is what makes gate.yml's `|| [ $? -eq 3 ]` safe: in CI, exit 3 cannot be a missing
+# tool or an unwired seam. Only the declared-environmental skip below can produce it.
+run_gate GATE_STRICT_SKIPS=true STAGE_RC_l0=3 STAGE_RC_lint=3
+assert_verdict BLOCKED 1 "several stages SKIPPED under strict skips"
+
+echo
+echo "== 5. spec-immutability: unverified is never green, but is not upgraded to a block by CI"
+run_gate STAGE_RC_spec_immutability=3
+assert_not_pass "spec-immutability SKIPPED"
+assert_verdict UNDETERMINED 3 "spec-immutability SKIPPED (local)"
+run_gate GATE_STRICT_SKIPS=true STAGE_RC_spec_immutability=3
+assert_verdict UNDETERMINED 3 "spec-immutability SKIPPED under strict skips (deliberate exception)"
+run_gate REQUIRE_SPEC_VERIFICATION=true STAGE_RC_spec_immutability=3
+assert_verdict BLOCKED 1 "spec-immutability SKIPPED + REQUIRE_SPEC_VERIFICATION=true"
+
+echo
+echo "== 6. conformance L2/L3: a DECLARED-absent capability may still pass — and is NAMED"
+run_gate STAGE_RC_conformance=3
+assert_verdict PASS 0 "conformance SKIPPED, no cluster declared"
+grep -qF "conformance-l2-l3" <<<"$OUT" \
+  && ok "the PASS headline names the declared L2/L3 gap" \
+  || bad "the PASS headline hides the declared L2/L3 gap"
+grep -qF "conformance-l2-l3" <<<"$SUMMARY" \
+  && ok "the step summary names the declared L2/L3 gap" \
+  || bad "the step summary hides the declared L2/L3 gap"
+run_gate CLUSTER_AVAILABLE=true STAGE_RC_conformance=3
+assert_verdict BLOCKED 1 "conformance SKIPPED despite CLUSTER_AVAILABLE=true"
+run_gate REQUIRE_CLUSTER_TESTS=true STAGE_RC_conformance=3
+assert_verdict BLOCKED 1 "conformance SKIPPED + REQUIRE_CLUSTER_TESTS=true with a touched subset"
+# A misspelled switch must leave the guard OFF (truthy()), never half-on.
+run_gate CLUSTER_AVAILABLE=ture STAGE_RC_conformance=3
+assert_verdict PASS 0 "CLUSTER_AVAILABLE=ture is NOT 'available' (no cluster was declared)"
+run_gate CLUSTER_AVAILABLE=TRUE STAGE_RC_conformance=3
+assert_verdict BLOCKED 1 "CLUSTER_AVAILABLE=TRUE IS a declaration (skip then blocks)"
+
+echo
+echo "== 7. the undetermined touched subset: unchanged (2026-08-31 false-green paths)"
+run_gate TR_RC=3 TR_REASON=on-base TR_OUT=
+assert_verdict "NOT APPLICABLE" 0 "subset undeterminable, reason on-base, all stages green"
+run_gate TR_RC=3 TR_REASON=no-base TR_OUT=
+assert_verdict BLOCKED 1 "subset undeterminable, reason no-base"
+run_gate TR_RC=3 TR_REASON=diff-failed TR_OUT=
+assert_verdict BLOCKED 1 "subset undeterminable, reason diff-failed"
+# Precedence: a stage that did not run outranks "nothing to gate" — the stronger, non-zero
+# headline must win, or a push-to-main run could hide a missing tool behind NOT APPLICABLE.
+run_gate TR_RC=3 TR_REASON=on-base TR_OUT= STAGE_RC_l1=3
+assert_not_pass "on-base AND l1 SKIPPED"
+assert_verdict UNDETERMINED 3 "on-base AND l1 SKIPPED (UNDETERMINED outranks NOT APPLICABLE)"
+
+echo
+echo "== 8. an UNUSABLE subset blocks (carried over from 47068ee): any other non-zero exit"
+for rc in 1 2 4; do
+  run_gate "TR_RC=${rc}" TR_REASON=unclassified-path TR_OUT=
+  assert_verdict BLOCKED 1 "touched-requirements.sh exited ${rc} (subset unusable, not empty)"
+done
+run_gate TR_RC=1 TR_REASON=unclassified-path TR_OUT=
+grep -qF "UNUSABLE" <<<"$SUMMARY" && ok "the step summary calls the subset UNUSABLE" \
+                                  || bad "the step summary does not report an unusable subset"
+
+echo
+echo "== 9. combinations: a FAILURE outranks a non-run, and the headline is the worst news"
+run_gate STAGE_RC_l0=1 STAGE_RC_l1=3
+assert_verdict BLOCKED 1 "l0 FAILED + l1 SKIPPED"
+run_gate STAGE_RC_spec_immutability=3 STAGE_RC_conformance=3
+assert_verdict UNDETERMINED 3 "spec-immutability SKIPPED + conformance declared-absent"
+
+echo
+if [ "$FAIL" -eq 0 ]; then echo "gate-decision tests: PASS ($PASS assertions)"; exit 0
+else echo "gate-decision tests: FAIL ($FAIL failed, $PASS passed)"; exit 1; fi
@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# ci/tests/touched-requirements-test-attribution.test.sh — regression tests for DETECTION
+# RULE 3 in ci/touched-requirements.sh: a change anywhere under `conformance/tests/<test>/`
+# attributes THAT TEST'S OWN `conformance.home.k3s/R-*` labels.
+#
+# THE GAP THESE LOCK DOWN (2026-09-12). The coarse path map keys `conformance/*` to
+# R-TEST-01..04 — the requirements about the HARNESS — and says nothing about what a given
+# test PROVES. So weakening `conformance/tests/.../check.sh` attributed R-TEST-01..04 and
+# nothing else: the merge gate ran the harness's self-tests and NOT the weakened test's own
+# requirement subset. Weakening (or deleting) a test is the one change that most needs the
+# requirement it certifies to be re-verified, and it was the change least likely to select it.
+# The content scan cannot close this: it reads only ADDED/REMOVED lines, so it sees a change
+# to the LABEL BLOCK but not one to the test BODY — exactly the case that matters.
+#
+# Also covers the two path-map entries added in the same change (infra/* -> R-ENV-01, and
+# R-TEST-06 on .gitea/*|ci/*), which is how the two L0 checks that are DELIBERATELY not
+# whole-repo-scoped get selected by the paths that can break them.
+#
+# Same harness as the sibling suites: the real script, pointed at a THROWAWAY git repo via
+# the REPO_ROOT override. No network, no cluster, the working repo is never touched.
+#
+# Run:  ci/tests/touched-requirements-test-attribution.test.sh   (or `make -C ci test`)
+set -euo pipefail
+
+CI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT="${CI_DIR}/touched-requirements.sh"
+
+PASS=0 FAIL=0
+ok()  { printf '  ok   %s\n' "$*"; PASS=$((PASS+1)); }
+bad() { printf '  FAIL %s\n' "$*" >&2; FAIL=$((FAIL+1)); }
+
+assert_present() {
+  if grep -qxF "$1" <<<"$2"; then ok "$3"
+  else bad "$3 (missing '$1' from: $(tr '\n' ' ' <<<"$2"))"; fi
+}
+assert_absent() {
+  if grep -qxF "$1" <<<"$2"; then bad "$3 (found unexpected '$1' in: $(tr '\n' ' ' <<<"$2"))"
+  else ok "$3"; fi
+}
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+git -C "$TMP" init -q -b main
+git -C "$TMP" config user.email [email protected]
+git -C "$TMP" config user.name t
+git -C "$TMP" config commit.gpgsign false
+
+# --- Baseline: two conformance tests, each declaring its own requirement labels ----------
+# TEST A: a flat l0-static test. TEST B: a test with a NESTED fixture dir, to prove the
+# walk-up from an arbitrary changed file to the enclosing test dir.
+mkdir -p "$TMP/conformance/tests/l0-static/alpha" \
+         "$TMP/conformance/tests/l2-behavioral/beta/fixtures" \
+         "$TMP/conformance/lib" "$TMP/infra" "$TMP/ci"
+
+cat > "$TMP/conformance/tests/l0-static/alpha/chainsaw-test.yaml" <<'YAML'
+# HEADER PROSE. This test used to also cover conformance.home.k3s/R-STALE-09: "true",
+# which is a REFERENCE in a comment, not a declaration, and must NOT be attributed.
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: alpha
+  labels:
+    conformance.home.k3s/R-ALPHA-01: "true"
+    conformance.home.k3s/R-ALPHA-02: "true"
+  annotations:
+    conformance.home.k3s/layer: "L0"
+spec: {}
+YAML
+# The check BODY deliberately contains NO R-ID text, so anything the scan finds for a
+# body-only edit came from rule 3 and not from the content scan.
+cat > "$TMP/conformance/tests/l0-static/alpha/check.sh" <<'SH'
+#!/usr/bin/env bash
+echo "assert something"
+SH
+
+cat > "$TMP/conformance/tests/l2-behavioral/beta/chainsaw-test.yaml" <<'YAML'
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: beta
+  labels:
+    conformance.home.k3s/R-BETA-07: "true"
+spec: {}
+YAML
+echo "seed: 1" > "$TMP/conformance/tests/l2-behavioral/beta/fixtures/data.yaml"
+
+echo "harness helper" > "$TMP/conformance/lib/helper.sh"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm baseline
+
+# ========================================================================================
+echo "== case 1: a BODY-ONLY edit to a test attributes that test's own labels"
+git -C "$TMP" checkout -q -b body-edit
+cat > "$TMP/conformance/tests/l0-static/alpha/check.sh" <<'SH'
+#!/usr/bin/env bash
+echo "assert something weaker"
+SH
+git -C "$TMP" add -A && git -C "$TMP" commit -qm weaken
+OUT="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set:\n%s\n---\n' "$OUT"
+assert_present "R-ALPHA-01" "$OUT" "body-only test edit attributes the test's own R-ALPHA-01"
+assert_present "R-ALPHA-02" "$OUT" "body-only test edit attributes the test's own R-ALPHA-02"
+assert_present "R-TEST-03"  "$OUT" "the conformance/* path map still applies (R-TEST-03)"
+assert_absent  "R-STALE-09" "$OUT" "an R-ID cited only in the test's HEADER COMMENT is NOT attributed"
+assert_absent  "R-BETA-07"  "$OUT" "an UNRELATED test's labels are NOT attributed"
+
+# ========================================================================================
+echo "== case 2: an edit to a NESTED file walks up to the enclosing test"
+git -C "$TMP" checkout -q -b nested-edit main
+echo "seed: 2" > "$TMP/conformance/tests/l2-behavioral/beta/fixtures/data.yaml"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm fixture
+OUT="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set:\n%s\n---\n' "$OUT"
+assert_present "R-BETA-07" "$OUT" "nested fixture edit attributes the enclosing test's R-BETA-07"
+assert_absent  "R-ALPHA-01" "$OUT" "nested fixture edit does NOT attribute a sibling test's labels"
+
+# ========================================================================================
+echo "== case 3: DELETING a test still attributes what it used to certify"
+# Removing the only verifier of a requirement must not be the cheapest way to make the gate
+# stop checking it — so the labels are read from the BASE when HEAD no longer has them.
+git -C "$TMP" checkout -q -b delete-test main
+git -C "$TMP" rm -rq "$TMP/conformance/tests/l0-static/alpha"
+git -C "$TMP" commit -qm "delete the alpha test"
+OUT="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set:\n%s\n---\n' "$OUT"
+assert_present "R-ALPHA-01" "$OUT" "deleting a test STILL attributes its R-ALPHA-01 (read from base)"
+assert_present "R-ALPHA-02" "$OUT" "deleting a test STILL attributes its R-ALPHA-02 (read from base)"
+
+# ========================================================================================
+echo "== case 4: a change OUTSIDE conformance/tests/ gains no test labels"
+git -C "$TMP" checkout -q -b lib-edit main
+echo "harness helper v2" > "$TMP/conformance/lib/helper.sh"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm lib
+OUT="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set:\n%s\n---\n' "$OUT"
+assert_present "R-TEST-02"  "$OUT" "a conformance/lib edit still attributes the harness requirements"
+assert_absent  "R-ALPHA-01" "$OUT" "a conformance/lib edit attributes NO individual test's labels"
+assert_absent  "R-BETA-07"  "$OUT" "a conformance/lib edit attributes NO individual test's labels (B)"
+
+# ========================================================================================
+echo "== case 5: path-map entries for the two DELIBERATELY path-scoped L0 checks"
+# infra/* -> R-ENV-01 (dev-nodes-provisioned-as-code reads nothing but infra/).
+git -C "$TMP" checkout -q -b infra-edit main
+printf 'resource "x" "y" {}\n' > "$TMP/infra/main.tf"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm infra
+OUT="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set:\n%s\n---\n' "$OUT"
+assert_present "R-ENV-01" "$OUT" "an infra/ edit attributes R-ENV-01 (was UNMAPPED: attributed nothing)"
+
+# ci/* -> ... R-TEST-06 (spec-immutability-enforced reads nothing but ci/ + the spec repo).
+git -C "$TMP" checkout -q -b ci-edit main
+printf 'echo hello\n' > "$TMP/ci/thing.sh"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm ci
+OUT="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set:\n%s\n---\n' "$OUT"
+assert_present "R-TEST-06"  "$OUT" "a ci/ edit attributes R-TEST-06 (the spec-immutability test's own ID)"
+assert_present "R-GITOPS-01" "$OUT" "a ci/ edit still attributes R-GITOPS-01"
+
+echo
+if [ "$FAIL" -eq 0 ]; then
+  echo "touched-requirements test-attribution tests: PASS (${PASS} assertions)"; exit 0
+fi
+echo "touched-requirements test-attribution tests: FAIL (${FAIL} failed, ${PASS} passed)" >&2
+exit 1
@@ -93,6 +93,141 @@ printf 'touched set (removal):\n%s\n---\n' "$OUT2"
 assert_absent  "R-DELDOC-01"  "$OUT2" "REMOVED whole-line comment R-ID is NOT attributed"
 assert_present "R-DELREAL-01"  "$OUT2" "REMOVED real-line R-ID IS attributed"

+# ---------------------------------------------------------------------------------------
+# PATH MAP — bootstrap/* (added 2026-09-13)
+#
+# WHY THIS IS LOCKED DOWN. path_requirements() keys `bootstrap/*` to R-STATE-03 +
+# R-GITOPS-01, and until 2026-09-13 the comment justifying it described
+# `bootstrap/standup.sh` as a file that carries the placeholder guards. That file has never
+# been on `main` (it landed only on unmerged prod-standup branches), so the comment was
+# stale and the entry looked like dead weight someone would tidy away. It is not dead: it
+# is what SELECTS conformance/tests/l0-static/placeholder-guard-coupling for the change
+# that eventually lands a placeholder guard under bootstrap/ — and that test discovers its
+# guard by content rather than by path, so it activates on exactly that change. Removing
+# the entry would let the change introducing a guard be gated by nothing, which is the
+# 2026-09-05 class. These assertions make the entry's deletion a test failure rather than a
+# silent loss of selection.
+#
+# NOTE the R-ID content scan must not be what produces these: `notes/` is outside the path
+# map precisely so the other cases isolate the scan, and here the file content cites no
+# R-ID at all, so any R-ID in the output came from the PATH.
+git -C "$TMP" checkout -q -b feature3 main
+mkdir -p "$TMP/bootstrap/flux"
+cat > "$TMP/bootstrap/flux/bootstrap.sh" <<'SH'
+#!/usr/bin/env bash
+# a bootstrap-path change that cites no requirement id of its own
+echo "flux bootstrap"
+SH
+git -C "$TMP" add -A && git -C "$TMP" commit -qm "touch bootstrap/"
+OUT3="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set (bootstrap/ path map):\n%s\n---\n' "$OUT3"
+assert_present "R-STATE-03"   "$OUT3" "bootstrap/* attributes R-STATE-03 (selects placeholder-guard-coupling)"
+assert_present "R-GITOPS-01"  "$OUT3" "bootstrap/* attributes R-GITOPS-01 (it IS the GitOps bootstrap path)"
+
+# And the neighbouring entry the same test leans on for its other half: clusters/* must
+# attribute R-ENV-02, which is what selects placeholder-guard-coupling's HALF A (the
+# authored-values sweep over clusters/<env> effective cluster-vars).
+git -C "$TMP" checkout -q -b feature4 main
+mkdir -p "$TMP/clusters/base"
+printf 'kind: ConfigMap\nmetadata:\n  name: cluster-vars\n' > "$TMP/clusters/base/cluster-vars.yaml"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm "touch clusters/"
+OUT4="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set (clusters/ path map):\n%s\n---\n' "$OUT4"
+assert_present "R-ENV-02"     "$OUT4" "clusters/* attributes R-ENV-02 (selects placeholder-guard-coupling HALF A)"
+assert_present "R-GITOPS-01"  "$OUT4" "clusters/* attributes R-GITOPS-01"
+
+# ---------------------------------------------------------------------------------------
+# PATH MAP — apps/*, the C2 UI, and the platform assembly (added 2026-09-19)
+#
+# These arms closed the largest remaining fail-open hole in the map. Before them, 49 tracked
+# app manifests (apps/wave-0, -1, -2, apps/vms) plus platform/homepage, platform/headlamp,
+# platform/gateway, platform/kubevirt, platform/crafty, platform/coredns, the snapshot/backup
+# machinery and platform/kustomization.yaml all attributed NOTHING — so a change to any of them
+# selected only the whole-repo-scoped checks, and every requirement-scoped L2 behaviour test
+# (default-deny, egress class, auth mode, C2 surface) was filtered out of the merge gate.
+#
+# The C2 case was already documented as a known gap in changed_diff()'s rule-3 comment: the ONLY
+# route to R-C2-01/02 was rule 3, i.e. editing the C2 test itself.
+#
+# As with bootstrap/ above, each fixture cites NO R-ID of its own, so any R-ID in the output came
+# from the PATH and not from the content scan.
+
+# apps/vms/* must win over apps/* — `case` takes the FIRST match, so arm ORDER is the property
+# under test here, not just the presence of both arms.
+git -C "$TMP" checkout -q -b feature-apps-vms main
+mkdir -p "$TMP/apps/vms/demo"
+printf 'kind: VirtualMachine\nmetadata:\n  name: demo\n' > "$TMP/apps/vms/demo/vm.yaml"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm "touch apps/vms/"
+OUT_VMS="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set (apps/vms/ path map):\n%s\n---\n' "$OUT_VMS"
+assert_present "R-PLAT-03"  "$OUT_VMS" "apps/vms/* attributes R-PLAT-03 (KubeVirt VM lifecycle)"
+assert_present "R-STATE-01" "$OUT_VMS" "apps/vms/* attributes R-STATE-01 (VM root/data volumes)"
+assert_absent  "R-PLAT-02"  "$OUT_VMS" "apps/vms/* does NOT fall through to the apps/* container arm (order holds)"
+
+# A plain ServiceDefinition under apps/ gets the container-workload set.
+git -C "$TMP" checkout -q -b feature-apps main
+mkdir -p "$TMP/apps/wave-1"
+printf 'kind: ServiceDefinition\nmetadata:\n  name: demo\n' > "$TMP/apps/wave-1/demo.yaml"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm "touch apps/wave-1/"
+OUT_APPS="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set (apps/ path map):\n%s\n---\n' "$OUT_APPS"
+assert_present "R-PLAT-02"  "$OUT_APPS" "apps/* attributes R-PLAT-02 (container workload render)"
+assert_present "R-NET-01"   "$OUT_APPS" "apps/* attributes R-NET-01 (default-deny applies to every app)"
+assert_present "R-NET-06"   "$OUT_APPS" "apps/* attributes the egress-class requirements"
+assert_present "R-IDP-02"   "$OUT_APPS" "apps/* attributes the auth-mode requirements"
+
+# homepage / headlamp ARE the command-centre surface.
+git -C "$TMP" checkout -q -b feature-c2 main
+mkdir -p "$TMP/platform/headlamp"
+printf 'kind: Deployment\nmetadata:\n  name: headlamp\n' > "$TMP/platform/headlamp/deployment.yaml"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm "touch platform/headlamp/"
+OUT_C2="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set (C2 path map):\n%s\n---\n' "$OUT_C2"
+assert_present "R-C2-01" "$OUT_C2" "platform/headlamp/* attributes R-C2-01 (was reachable only by editing the C2 test)"
+assert_present "R-C2-02" "$OUT_C2" "platform/headlamp/* attributes R-C2-02"
+
+# platform/kustomization.yaml is the assembly: one deleted line disables a whole component.
+git -C "$TMP" checkout -q -b feature-assembly main
+mkdir -p "$TMP/platform"
+printf 'resources:\n  - cilium\n  - longhorn\n' > "$TMP/platform/kustomization.yaml"
+git -C "$TMP" add -A && git -C "$TMP" commit -qm "touch platform/kustomization.yaml"
+OUT_ASM="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set (platform assembly):\n%s\n---\n' "$OUT_ASM"
+assert_present "R-GITOPS-01" "$OUT_ASM" "platform/kustomization.yaml attributes R-GITOPS-01 (component assembly)"
+
+# ---------------------------------------------------------------------------------------
+# THE ID PATTERN MUST ALLOW A DIGIT IN THE WORKSTREAM SEGMENT (added 2026-09-13)
+#
+# The content scan's pattern was `R-[A-Z]+-[0-9]+`, which CANNOT match `R-C2-01` or
+# `R-C2-02` — `[A-Z]+` consumes the `C` and then demands a `-` where the `2` is. Those are
+# the only two registry IDs whose workstream segment carries a digit, and the scan was blind
+# to BOTH, in the fail-OPEN direction: a change self-declaring a C2 requirement contributed
+# it to nobody, so the C2 conformance tests were filtered out of the merge gate. Found while
+# wiring conformance/tests/l0-static/c2-root-surface, which closes those two coverage gaps.
+#
+# `notes/` is outside path_requirements() on purpose, so the IDs below can only have come
+# from the CONTENT SCAN. A neighbouring all-letter ID is asserted too, so a regex that
+# somehow matched only the digit form would still fail here.
+git -C "$TMP" checkout -q -b feature5 main
+cat > "$TMP/notes/c2.yaml" <<'YAML'
+kind: Test
+metadata:
+  labels:
+    conformance.home.k3s/R-C2-01: "true"
+    conformance.home.k3s/R-C2-02: "true"
+    conformance.home.k3s/R-OBS-04: "true"
+YAML
+git -C "$TMP" add -A && git -C "$TMP" commit -qm "declare R-C2-01 / R-C2-02"
+OUT5="$(REPO_ROOT="$TMP" BASE_REF=main "$SCRIPT" 2>/dev/null)"
+printf 'touched set (digit in the workstream segment):\n%s\n---\n' "$OUT5"
+assert_present "R-C2-01"  "$OUT5" "an R-ID with a DIGIT in the workstream segment IS attributed (R-C2-01)"
+assert_present "R-C2-02"  "$OUT5" "the second such ID is attributed too (R-C2-02)"
+assert_present "R-OBS-04" "$OUT5" "an all-letter workstream segment still works (control)"
+# The pattern must not become so loose that a non-ID token is read as a requirement: a bare
+# numeric workstream is not a registry shape, and attributing one would WIDEN the gate on
+# noise (over-broad selection, never a false green, but noisy and misleading).
+assert_absent  "R-1-01"   "$OUT5" "a purely numeric workstream segment is not invented from thin air"
+
 echo
 if [ "$FAIL" -eq 0 ]; then echo "touched-requirements tests: PASS ($PASS assertions)"; exit 0;
 else echo "touched-requirements tests: FAIL ($FAIL failed, $PASS passed)"; exit 1; fi
@@ -21,8 +21,12 @@
 #      the R-IDs that policies/ServiceDefinitions self-declare (docs/14 + ADR-0011).
 #      Untouched lines and prose are NOT scanned; see changed_diff() for why.
 #   2. A coarse path->requirement fallback for changes that don't self-declare IDs.
+#   3. For a change anywhere under `conformance/tests/<test>/`: THAT TEST'S OWN requirement
+#      labels, read from its chainsaw-test.yaml. See test_requirements_for_path().
 # The coarse map (2) NEVER overrides an explicit tag; it only widens coverage for
-# untagged changes so nothing silently escapes the gate.
+# untagged changes so nothing silently escapes the gate. (3) is the same principle applied
+# to the tests themselves: editing or weakening a test must be gated by the requirements
+# that test CERTIFIES, not merely by R-TEST-0x.
 set -euo pipefail
 CI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
@@ -173,6 +177,23 @@ path_requirements() {
  case "$1" in
    catalog/*)                 echo "R-GITOPS-02" ;;
    schemas/*)                 echo "R-GITOPS-02" ;;
+    # apps/* was UNMAPPED until 2026-09-19, and it is the largest such hole in the map: 49 tracked
+    # manifests (apps/wave-0, -1, -2, apps/vms) that describe every workload on the cluster. A change
+    # adding or editing an app attributed NOTHING, so the merge gate ran only the whole-repo-scoped
+    # checks and none of the requirement-scoped L2 behaviour tests — default-deny enforcement, egress
+    # class enforcement, auth-mode enforcement — which are exactly what a new or edited app can
+    # violate. Kyverno admission and the L0 egress-path check are real backstops, but "admission will
+    # catch it at apply time" is post-merge, and the gate exists to catch it before.
+    #
+    # ORDER MATTERS: `case` takes the FIRST match, so apps/vms/* must precede apps/*.
+    # apps/vms/ are KubeVirt VMs (R-PLAT-03 lifecycle) with root/data volumes (R-STATE-01), still
+    # subject to default-deny (R-NET-01).
+    apps/vms/*)                echo "R-PLAT-03 R-NET-01 R-STATE-01" ;;
+    # Everything else under apps/ is a ServiceDefinition rendered by catalog/render.py: a container
+    # workload (R-PLAT-02) rendered from the catalog (R-GITOPS-02), carrying the egress-class
+    # (R-NET-05/06/07) and auth-mode (R-IDP-02/R-IDP-06) labels that admission requires, under
+    # default-deny (R-NET-01).
+    apps/*)                    echo "R-PLAT-02 R-GITOPS-02 R-NET-01 R-NET-05 R-NET-06 R-NET-07 R-IDP-02 R-IDP-06" ;;
    platform/kyverno/*)        echo "R-TEST-01 R-NET-01 R-SEC-01" ;;
    platform/cilium/*)         echo "R-NET-01 R-NET-02 R-NET-05" ;;
    platform/longhorn/*)       echo "R-STATE-01 R-STATE-02" ;;
@@ -204,22 +225,137 @@ path_requirements() {
    platform/keycloak/*)       echo "R-IDP-01 R-IDP-02 R-IDP-03 R-IDP-04 R-IDP-05 R-IDP-06" ;;
    platform/oauth2-proxy/*)   echo "R-IDP-02 R-IDP-06" ;;
    platform/image-automation/*) echo "R-UPD-01 R-UPD-02" ;;
+    # The C2 UI was UNMAPPED until 2026-09-19. This is the gap named explicitly in changed_diff()'s
+    # rule-3 comment above: "path_requirements() has no arm for platform/homepage/* or
+    # platform/headlamp/* either, so the ONLY route to R-C2-01/02 was rule 3 (editing the C2 test
+    # itself)". homepage + headlamp ARE the command-centre surface (registry: R-C2-01/02 ->
+    # docs/12-command-center-ui.md), so editing them must select the C2 tests.
+    platform/homepage/*|platform/headlamp/*) echo "R-C2-01 R-C2-02" ;;
+    # KubeVirt is the VM platform itself (R-PLAT-03); its virt-* components are also scrape targets.
+    platform/kubevirt/*)       echo "R-PLAT-03 R-OBS-01" ;;
+    # The shared ingress Gateway: the L2-announced VIP every HTTP service answers on (R-DNS-01), the
+    # TLS listeners and their certificates (R-TLS-01/02), under default-deny (R-NET-01).
+    platform/gateway/*)        echo "R-DNS-01 R-TLS-01 R-TLS-02 R-NET-01" ;;
+    # CoreDNS is cluster DNS resolution (R-DNS-01).
+    platform/coredns/*)        echo "R-DNS-01" ;;
+    # crafty is a first-class app living under platform/: a container workload with a Longhorn PVC and
+    # its OWN L4 LoadBalancer VIP (Minecraft 25565 is not HTTP, so it does not use the Gateway).
+    platform/crafty/*)         echo "R-PLAT-02 R-NET-01 R-DNS-01 R-STATE-01" ;;
+    # Snapshot machinery is the storage/DR path: CSI snapshots (R-STATE-01) feeding backup (R-STATE-03).
+    platform/external-snapshotter/*|platform/backup/*) echo "R-STATE-01 R-STATE-03" ;;
+    # runbooks/ IS the R-OBS-04 surface: alert-runbooks-resolvable asserts every alert's runbook_url
+    # resolves to a served page, and runbooks/serving/ is the Deployment that serves them. That check
+    # is whole-repo-scoped so it runs regardless, but the attribution should still be honest — a
+    # runbook change is an observability change.
+    runbooks/*)                echo "R-OBS-04" ;;
+    # platform-config/ is the env-specific configuration Flux substitutes into and applies.
+    platform-config/*|platform-config-cdi/*) echo "R-ENV-02 R-GITOPS-01" ;;
+    # platform/kustomization.yaml is the ASSEMBLY: the list of platform components Flux applies.
+    # Deleting one line there disables an entire component (cilium, longhorn, velero...) while every
+    # file it points at stays perfectly valid on disk, so nothing else in the map would attribute the
+    # change. That is the most consequential single-line edit in the repo and it attributed nothing.
+    platform/kustomization.yaml) echo "R-GITOPS-01" ;;
+    # .sops.yaml holds the encryption rules (which paths must be encrypted, with which keys). A change
+    # here can silently stop a new secret path from being encrypted, which is R-SEC-01's whole point.
+    .sops.yaml)                echo "R-SEC-01 R-GITOPS-01" ;;
    conformance/*)             echo "R-TEST-01 R-TEST-02 R-TEST-03 R-TEST-04" ;;
+    # infra/ was UNMAPPED until 2026-09-12 — the OpenTofu + Ansible that provision the dev
+    # nodes. conformance/tests/l0-static/dev-nodes-provisioned-as-code reads NOTHING but
+    # infra/, yet an infra/ edit attributed ZERO requirements, so the one check that asserts
+    # the nodes are provisioned as code was filtered out of every change that could break it.
+    # That test's invariant IS path-scoped (it is deliberately NOT whole-repo-scoped; see its
+    # chainsaw-test.yaml), and the correct fix for a path-scoped invariant is a path-map entry.
+    infra/*)                   echo "R-ENV-01" ;;
    clusters/*)                echo "R-GITOPS-01 R-ENV-02" ;;
-    # bootstrap/ was UNMAPPED until 2026-09-06, and the omission was load-bearing:
-    # bootstrap/standup.sh carries the placeholder guards that decide whether `velero` may be
-    # enabled against a real backup endpoint. A change touching standup.sh ALONGSIDE any
-    # already-mapped path scoped the L0 run to that other path's requirements and silently
-    # excluded conformance/tests/l0-static/placeholder-guard-coupling — the check that exists
-    # precisely to catch a guard/value mismatch. The 2026-09-05 guard bug (a prefix glob that
-    # stopped matching when the value it guards changed, in a different file) is exactly the
-    # class that omission would hide.
+    # bootstrap/ was UNMAPPED until 2026-09-06. The entry STAYS, but its original rationale
+    # was written against a file that is not here, and that is corrected on 2026-09-13:
+    # it claimed "bootstrap/standup.sh carries the placeholder guards that decide whether
+    # `velero` may be enabled against a real backup endpoint". bootstrap/standup.sh HAS NEVER
+    # BEEN ON `main` — it was not deleted (no deletion commit exists anywhere), it landed only
+    # on unmerged prod-standup branches. `git ls-tree main bootstrap/` lists README.md, flux/,
+    # gitea/, sops/. So R-STATE-03 here is ANTICIPATORY, not descriptive.
+    #
+    # WHY IT IS STILL RIGHT. conformance/tests/l0-static/placeholder-guard-coupling DISCOVERS
+    # its guard (any tracked *.sh defining `<name>_is_placeholder()`) instead of hardcoding a
+    # path, so the moment a standup guard lands under bootstrap/ that test's coupling half
+    # activates — and this entry is what selects the test for the change that lands it.
+    # Deleting the entry would mean the change introducing a placeholder guard is gated by
+    # nothing, which is the 2026-09-05 class (a prefix glob that stopped matching when the
+    # value it guards changed, in a different file) left to reintroduce itself. R-GITOPS-01 is
+    # descriptive today: bootstrap/flux/, gitea/ and sops/ ARE the GitOps bootstrap path.
+    # Locked down by ci/tests/touched-requirements.test.sh's path-map section.
    bootstrap/*)               echo "R-STATE-03 R-GITOPS-01" ;;
-    .gitea/*|ci/*)             echo "R-GITOPS-01 R-TEST-02 R-TEST-03" ;;
+    # R-TEST-06 added 2026-09-12. The comment in changed_diff()'s rule 3 above records why it
+    # was ABSENT: R-TEST-06 used to be enforced by the spec-immutability STAGE and carried by no
+    # Chainsaw test, so attributing it made the coverage `--require` check false-block. It is now
+    # carried by conformance/tests/l0-static/spec-immutability-enforced — whose entire input
+    # surface is ci/ — so a ci/ change must attribute it, or the test that proves the
+    # spec-immutability mechanism is still load-bearing runs on nothing that can break it.
+    .gitea/*|ci/*)             echo "R-GITOPS-01 R-TEST-02 R-TEST-03 R-TEST-06" ;;
    *) : ;;
  esac
 }

+# ---------------------------------------------------------------------------------
+# A CHANGED TEST ATTRIBUTES THE REQUIREMENTS IT CERTIFIES (detection rule 3).
+#
+# THE GAP THIS CLOSES (2026-09-12). The path map keys `conformance/*` to
+# R-TEST-01..04 — the requirements about the HARNESS. It says nothing about what a given
+# test PROVES. So editing `conformance/tests/l2-behavioral/tenant-isolation/check.sh` to
+# weaken or delete an assertion attributed R-TEST-01..04 and nothing else: the merge gate
+# then ran the harness's self-tests and NOT the weakened test's own requirement subset.
+# Weakening a test is the one change that most needs the requirement it certifies to be
+# re-verified, and it was the change least likely to select it.
+#
+# The `conformance.home.k3s/R-*: "true"` labels on a test ARE the authoritative declaration of
+# what it verifies (lib/coverage.py reads the same labels); this reads them directly. Note the
+# content scan in main() only sees ADDED/REMOVED lines, so it catches a change to the LABEL
+# BLOCK but not a change to the test BODY — which is exactly the case that matters here.
+#
+# WHY IT READS HEAD *OR* THE BASE: a change that DELETES a test, or deletes its
+# chainsaw-test.yaml, must still attribute what that test used to certify — otherwise removing
+# the only verifier of a requirement is the cheapest way to make the gate stop checking it.
+# HEAD first (the post-change truth), base as the fallback (the deleted case). Fail-closed:
+# this function can only ADD requirements, never remove one.
+: "${CONF_TEST_LABEL_PREFIX:=conformance.home.k3s}"   # == CONF_LABEL_PREFIX, conformance/lib/common.sh
+
+file_text_head_or_base() {
+  local path="$1"
+  git -C "$REPO_ROOT" show "HEAD:${path}" 2>/dev/null && return 0
+  git -C "$REPO_ROOT" show "${BASE}:${path}" 2>/dev/null && return 0
+  return 0
+}
+
+# test_requirements_for_path <changed-path> -> space-separated R-IDs (possibly empty).
+# Walks UP from the changed file to the nearest ancestor directory carrying a
+# chainsaw-test.yaml, so it works for any file in a test dir (check.sh, mutations.py,
+# fixtures, the chainsaw-test.yaml itself) and for nested test layouts.
+test_requirements_for_path() {
+  local f="$1" dir yaml text
+  case "$f" in conformance/tests/*/*) ;; *) return 0 ;; esac
+  dir="${f%/*}"
+  while :; do
+    case "$dir" in
+      conformance/tests|conformance|.|"") return 0 ;;
+      */*) ;;
+      *) return 0 ;;
+    esac
+    yaml="${dir}/chainsaw-test.yaml"
+    text="$(file_text_head_or_base "$yaml")"
+    if [ -n "$text" ]; then
+      # Whole-line `#` comments are dropped first — same "reference, not declaration" rule the
+      # content scan applies (changed_diff() rule 3): a label shown inside a header example is
+      # documentation. Only a real YAML mapping line counts.
+      printf '%s\n' "$text" \
+        | grep -vE '^[[:space:]]*#' \
+        | sed -nE "s#^[[:space:]]*${CONF_TEST_LABEL_PREFIX}/(R-[A-Z0-9]+-[0-9]+):[[:space:]]*[\"']?true.*#\1#p" \
+        | tr '\n' ' '
+      return 0
+    fi
+    dir="${dir%/*}"
+  done
+}
+
 main() {
  local files reqs="" rc=0 base_sha head_sha local_main merge_base

@@ -253,9 +389,27 @@ main() {
  while IFS= read -r f; do
    [ -n "$f" ] || continue
    reqs+=" $(path_requirements "$f")"
+    # Detection rule 3: a change under conformance/tests/<test>/ attributes THAT TEST'S own
+    # requirement labels, so weakening a test is gated by what the test certifies.
+    reqs+=" $(test_requirements_for_path "$f")"
  done <<< "$files"

  # Self-declared R-IDs on the ADDED/REMOVED lines of the change (see changed_diff).
+  #
+  # THE ID PATTERN IS `R-[A-Z0-9]+-[0-9]+`, NOT `R-[A-Z]+-[0-9]+`. The WORKSTREAM segment may
+  # contain a DIGIT: `R-C2-01` and `R-C2-02` (command & control UI) are the only two such IDs
+  # in conformance/requirements/registry.yaml today, and the stricter pattern silently failed
+  # to match BOTH of them — `[A-Z]+` consumes the `C` and then demands a `-` where the `2` is.
+  # Every other consumer in the repo already allows the digit: test_requirements_for_path()
+  # twenty lines above uses `R-[A-Z0-9]+-[0-9]+`, as do conformance/lib/coverage.py,
+  # conformance/lib/status.py and conformance/lib/run_l1_offline.py. This grep was the lone
+  # dissenter, and it dissented by UNDER-attributing — the fail-OPEN direction. A change that
+  # retyped a `conformance.home.k3s/R-C2-01` tag, or a manifest self-declaring R-C2-02 from a
+  # path the map keys elsewhere, contributed those IDs to NOBODY, so the C2 tests were
+  # filtered out of the merge gate. Same defect class as the map's `*) : ;;` arm: a miss that
+  # reads as "nothing touched". path_requirements() has no arm for platform/homepage/* or
+  # platform/headlamp/* either, so before this fix the ONLY route to R-C2-01/02 was rule 3
+  # (editing the C2 test itself). Regression-tested in ci/tests/touched-requirements.test.sh.
  # `^[+-]` keeps hunk headers (`@@`) and the `+++`/`---` file headers out of scope.
  # `sed 's/^[+-]//'` then strips the single-char diff marker (safe: -U0 emits one), so
  #   what remains is the SOURCE line, and `grep -vE '^[[:space:]]*#'` drops whole-line
@@ -269,7 +423,7 @@ main() {
    | grep -vE '^(\+\+\+|---)' \
    | sed -E 's/^[+-]//' \
    | grep -vE '^[[:space:]]*#' \
-    | grep -hoE 'R-[A-Z]+-[0-9]+' \
+    | grep -hoE 'R-[A-Z0-9]+-[0-9]+' \
    | tr '\n' ' ' || true)"

  # Normalize: split, unique, sort. Emit to stdout.
@@ -21,6 +21,15 @@ YAMLLINT_VERSION="1.35.1"
 KUBECTL_VERSION="1.36.4"
 YQ_VERSION="4.44.6"

+# Alert-rule unit tests (promtool test rules) — the L0 check
+# conformance/tests/l0-static/alert-rules-unit-tested runs every
+# platform/**/*.promtool-test.yaml through it. MUST stay in lockstep with
+# infra/devcontainer/versions.env (which bakes it into the image) AND with the Prometheus
+# version running on prod, because promtool IS the rule engine: verified 2026-09-12 as
+# v3.14.0-distroless via `kubectl get prometheus -n monitoring -o jsonpath='{.items[*].spec.version}'`.
+# Shipped inside the prometheus release tarball, not as a separate release.
+PROMTOOL_VERSION="3.14.0"
+
 # ServiceDefinition JSON-Schema validation (schemas/validate.sh). Pip-installed;
 # pinned here so CI and a laptop validate against the exact same validator.
 CHECK_JSONSCHEMA_VERSION="0.29.4"
@@ -1,5 +1,19 @@
 # clusters/

+> **STATUS NOTE (2026-09-29) — read before trusting the "Phase 0" framing below.**
+> This document speaks as though no cluster exists and the platform is scaffolding. **A
+> three-node k3s cluster has existed for weeks** and Flux has been reconciling against it.
+> Gitea is live, the Actions runner `incluster-dind` is online, and `main` is a protected
+> branch. Where the text says "Phase 0", "stub", or "no cluster exists", read it as
+> describing a **live gap** rather than an expected stage — most importantly, L2/L3
+> conformance still does not run in CI (`vars.CLUSTER_AVAILABLE` is unset), which is a real
+> coverage hole, not a phase.
+>
+> This mismatch is not cosmetic. A month of "the gate enforces this" claims rested on
+> documentation rather than measurement, and `main` was unprotected with zero runners
+> registered the whole time. **Query the live API before asserting platform state.**
+
+
 Flux entrypoints and the environment-overlay model (**R-ENV-02**, **R-GITOPS-01/02/03**).

 Governing spec: [`docs/05-gitops-and-delivery.md`](../../home-network-k3s/docs/05-gitops-and-delivery.md),
@@ -99,7 +99,9 @@ data:
  # (CILIUM_LB_POOL_*, and keycloak-db's S3_BACKUP_ENDPOINT + CNPG_BACKUP_PATH: the Cluster lives at
  # platform/keycloak/postgres-cluster.yaml but is rendered by platform-config, which is the ONLY
  # tier that lists it), crafty (CRAFTY_L4_VIP), apps-wave-0 (nextcloud-db + semaphore-db:
-  # S3_BACKUP_ENDPOINT, CNPG_BACKUP_PATH), velero (S3_BACKUP_ENDPOINT, S3_BACKUP_REGION,
+  # S3_BACKUP_ENDPOINT, CNPG_BACKUP_PATH; pihole + pihole-dns: PIHOLE_DNS_VIP, LAN_CIDR, plus
+  # GATEWAY_VIP/UNIFI_L4_VIP/CRAFTY_L4_VIP read BY pihole to author its LAN split-horizon answers),
+  # velero (S3_BACKUP_ENDPOINT, S3_BACKUP_REGION,
  # VELERO_BACKUP_BUCKET, VELERO_BACKUP_PREFIX), apps-vms (UNIFI_L4_VIP). A ${TOKEN} in an
  # UNSUBSTITUTED path would ship the literal string into the cluster.
  #
@@ -159,6 +161,30 @@ data:
  # HTTPS Gateway cannot express (raw TCP/UDP), so they hold their own stable address:
  UNIFI_L4_VIP: "192.168.1.54"               # UniFi controller VM: inform/STUN/adoption (apps/vms/unifi)
  CRAFTY_L4_VIP: "192.168.1.55"              # Crafty: Minecraft Java (TCP) + Bedrock (UDP) game ports
+  # PiHole's DNS listener: udp/53 + tcp/53 for LAN CLIENTS (apps/wave-0/pihole-dns.yaml). It is a
+  # THIRD pinned L4 VIP for the same reason as the two above — the `shared` Gateway is an L7 HTTPS
+  # terminator and cannot express DNS at all (udp/53 especially). It must NOT be ${GATEWAY_VIP}:
+  # LAN clients are pointed at this address as their resolver, and it has to stay put across
+  # reschedules, so it is pinned by lbipam.cilium.io/ips rather than taken from the pool head.
+  #
+  # WHY A SEPARATE ADDRESS AND NOT THE GATEWAY VIP: every `<svc>.${BASE_DOMAIN}` name resolves TO
+  # the Gateway VIP. Serving DNS from the same address would be legal but conflates "the thing that
+  # answers where services live" with "a service", and it would put LAN resolution behind the
+  # Gateway Service's own lifecycle. Keep them separate.
+  #
+  # dev  -> 192.168.1.56  (base default; next free after crafty .55 in dev's .53-.60 pool)
+  # prod -> 192.168.2.23  (next free after crafty .22 in prod's .20-.30 pool; see clusters/prod)
+  PIHOLE_DNS_VIP: "192.168.1.56"             # PiHole: authoritative LAN DNS for ${BASE_DOMAIN}
+
+  # The FLAT LAN this cluster's nodes and LB VIPs live on, in CIDR form. Consumed as the ingress
+  # peer of the PiHole DNS CiliumNetworkPolicy (apps/wave-0/pihole-dns.yaml): a resolver reachable
+  # from `world` is an open resolver and an amplification reflector, so the allow is scoped to this
+  # CIDR, not to Cilium's `world` entity the way the unifi/crafty game-port allows are. It is the
+  # same /24 the node IPs and ${CILIUM_LB_POOL_START}..${CILIUM_LB_POOL_STOP} come out of.
+  #
+  # dev  -> 192.168.1.0/24  (Proxmox LAN; nodes .50/.51/.52)
+  # prod -> 192.168.2.0/24  (prod LAN; nodes .10/.11/.12)
+  LAN_CIDR: "192.168.1.0/24"                 # ingress scope for the PiHole DNS listener

  # --- Bulk (external NFS) storage host (docs/04 bulk tier) ---------------------------------------
  # THE address of the Proxmox host whose ZFS datasets back every `class: bulk` volume: the media
@@ -0,0 +1,31 @@
+---
+# Conformance identities (ns + conformance-runner + conformance-trigger RBAC).
+#
+# NON-GATING, exactly like apps-vms: `wait: false` and its own Kustomization, so a conformance
+# identity can never gate the platform or app tiers. A test harness that stalls the estate it is
+# meant to verify is worse than no harness.
+#
+# dependsOn platform-config only — it needs nothing from the app waves, and nothing in the app
+# waves needs it.
+#
+# NOTE: this reconciles RBAC that is INERT until
+# platform/kyverno/admission/conformance-trigger-job-shape.yaml is also enforcing. That policy
+# ships in the `platform` tier, which reconciles before this. Do not reorder them so that the
+# trigger identity can exist while the policy bounding it does not.
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: conformance
+  namespace: flux-system
+spec:
+  interval: 10m
+  retryInterval: 2m
+  timeout: 5m
+  prune: true
+  wait: false
+  dependsOn:
+    - name: platform-config
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  path: ./conformance/incluster
@@ -34,8 +34,12 @@ spec:
    kind: GitRepository
    name: flux-system
  path: ./platform/homepage
-  # Homepage references no ${VARS} today; the substitution is retained for parity with the other
-  # tiers / future overlay knobs.
+  # LOAD-BEARING, not parity decoration (the comment here used to say the opposite). This component
+  # references ${BASE_DOMAIN} in TWO places: httproute.yaml's apex hostname, and EVERY tile href in
+  # configmap.yaml. Without this substitution the token is applied LITERALLY — the apex route binds
+  # the host `${BASE_DOMAIN}`, which matches no Gateway listener, and every link on the operator's
+  # front door points at a host that does not exist — while Flux still reports this Kustomization
+  # Ready. It fails OPEN. Asserted by conformance/tests/l0-static/c2-root-surface (5).
  postBuild:
    substituteFrom:
      - kind: ConfigMap
@@ -33,6 +33,7 @@ resources:
  - apps-wave-2.yaml     # Flux Kustomization -> ./apps/wave-2 (dependsOn apps-wave-1)
  # VM tier (KubeVirt) — non-gating (wait:false), separate lifecycle from the app waves.
  - apps-vms.yaml        # Flux Kustomization -> ./apps/vms (dependsOn platform-config)
+  - conformance.yaml     # Flux Kustomization -> ./conformance/incluster (non-gating; R-SEC-02 trigger identity)
  # oauth2-proxy forward-auth — POST-platform tier (dependsOn platform-config, wait:false). A leaf
  # service that needs Keycloak + trusted TLS + split-horizon DNS must NOT sit in the gating
  # `platform` tier, where it self-gated its own dependencies into a cold-start deadlock (twice).
@@ -50,6 +51,13 @@ resources:
  # reverse-proxy sidecar (Option B). POST-platform tier (dependsOn platform-config, wait:false); same
  # non-gating leaf-UI rationale as headlamp/homepage/oauth2-proxy (a UI must never gate the platform).
  - crafty.yaml          # Flux Kustomization -> ./platform/crafty (dependsOn platform-config)
+  # Alert runbooks — POST-platform tier (dependsOn platform-config, wait:false). Serves the 34
+  # runbooks the alert rules' `runbook_url` annotations point at, at <apex>/runbooks/<name>; before
+  # this tier existed that path was a 404 and every alert handed the operator a dead link. Same
+  # non-gating leaf rationale as headlamp/homepage/crafty. Carries NO postBuild substitution on
+  # purpose — it renders documentation containing `${...}` shell examples that envsubst would empty;
+  # see clusters/base/runbooks.yaml.
+  - runbooks.yaml        # Flux Kustomization -> ./runbooks (dependsOn platform-config)
  # Velero backup controller — POST-platform tier (dependsOn platform-config, wait:false). A backup
  # controller must NEVER gate the platform chain; same non-gating rationale as headlamp/oauth2-proxy.
  # Carries velero-cloud.sops.yaml, so clusters/dev adds a SOPS decryption patch for it (by name).
@@ -0,0 +1,57 @@
+---
+# Flux Kustomization: alert runbooks — reconciles ./runbooks.
+#
+# WHAT THIS SERVES. Every alert rule in this repo carries
+# `runbook_url: "https://${BASE_DOMAIN}/runbooks/<name>"` — 42 annotations over 34 distinct names.
+# Until this tier existed that path returned 404 on the live cluster, so every alert that reached a
+# human handed them a dead link at the moment they needed help. This Kustomization renders the
+# markdown under ./runbooks into a ConfigMap and a two-replica nginx that serves it at that exact
+# prefix. See runbooks/README.md and runbooks/serving/httproute.yaml.
+#
+# POST-PLATFORM TIER (dependsOn platform-config), NON-GATING (wait:false) — the same placement and
+# the same reasoning as homepage/headlamp/oauth2-proxy. It needs the wildcard TLS cert, the shared
+# Gateway (including the `https-apex` listener) and split-horizon DNS, all of which arrive with
+# `platform` + `platform-config`; and a leaf web server must never be able to stall the platform
+# chain, which is the whole lesson of DECISIONS-LOG's "Headlamp gating stall". wait:false guarantees
+# its health can never gate anything even if something is later mistakenly pointed dependsOn it.
+#
+# NO postBuild.substituteFrom — THE ONE DELIBERATE DIVERGENCE FROM EVERY OTHER TIER, AND THE MOST
+# IMPORTANT LINE IN THIS FILE.
+# This tier renders the runbook PROSE into a ConfigMap, and runbooks are full of shell: `$POD`,
+# `$(kubectl ...)`, and — unavoidably, since they document these very annotations — the literal text
+# `${BASE_DOMAIN}`. Flux's postBuild substitution runs envsubst over the ENTIRE built stream, and it
+# FAILS OPEN: an undefined `${X}` becomes the empty string while the Kustomization still reports
+# Ready (DECISIONS-LOG 2026-09-01 — that is how `k8sServiceHost` was emptied and Cilium broke on 2
+# of 3 dev nodes). Enabled here it would silently mutilate the documentation: every braced expansion
+# in every command example blanked, in a file nobody re-reads after writing. Worse, the L0 check
+# `conformance/tests/l0-static/flux-postbuild-substitution` scans only files reachable through
+# kustomization `resources:`, not `configMapGenerator` inputs, so the damage would be invisible to
+# the gate as well.
+# The fix is to have nothing to substitute. The only knob this tier would have wanted is the apex
+# hostname, and runbooks/serving/httproute.yaml avoids needing it by declaring NO `hostnames:` and
+# inheriting the `https-apex` listener's own hostname instead. So this tier is
+# environment-independent by construction and R-ENV-02 ("authored once, promoted dev -> prod") holds
+# without substitution rather than because of it.
+# IF A FUTURE KNOB EVER GENUINELY NEEDS SUBSTITUTION HERE: do not add substituteFrom to this
+# Kustomization. Split the serving manifests into their own substituted tier and leave the content
+# ConfigMap in an unsubstituted one, or the runbooks lose their shell examples.
+#
+# NO SOPS decryption stanza: this tier carries no encrypted Secret (markdown plus five plain
+# manifests), so — like homepage — neither clusters/dev nor clusters/prod patches it.
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: runbooks
+  namespace: flux-system
+spec:
+  interval: 10m
+  retryInterval: 2m
+  timeout: 5m
+  prune: true
+  wait: false
+  dependsOn:
+    - name: platform-config   # wildcard TLS + Gateway (incl. the https-apex listener) first
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  path: ./runbooks
@@ -122,6 +122,23 @@ patches:
          provider: sops
          secretRef:
            name: sops-age
+  # apps-vms (the KubeVirt VM tier, clusters/base/apps-vms.yaml) gained its FIRST encrypted Secret
+  # on 2026-09-14: apps/vms/unifi/unifi-uos-installer.sops.yaml, the operator's UOS installer URL,
+  # which 30-virtualmachine.yaml mounts into the guest as a disk. Without this stanza kustomize
+  # would hand Flux the raw SOPS document and the VM would mount a disk full of ciphertext — the
+  # failure is silent from the cluster's point of view (the Secret applies fine), so the stanza is
+  # as load-bearing as the file itself. The `sops-age` Secret is out-of-band (name only).
+  - patch: |-
+      apiVersion: kustomize.toolkit.fluxcd.io/v1
+      kind: Kustomization
+      metadata:
+        name: apps-vms
+        namespace: flux-system
+      spec:
+        decryption:
+          provider: sops
+          secretRef:
+            name: sops-age
  - patch: |-
      apiVersion: source.toolkit.fluxcd.io/v1
      kind: GitRepository
@@ -113,6 +113,23 @@ patches:
          provider: sops
          secretRef:
            name: sops-age
+  # apps-vms (the KubeVirt VM tier, clusters/base/apps-vms.yaml) gained its FIRST encrypted Secret
+  # on 2026-09-14: apps/vms/unifi/unifi-uos-installer.sops.yaml, the operator's UOS installer URL,
+  # which 30-virtualmachine.yaml mounts into the guest as a disk. Without this stanza kustomize
+  # would hand Flux the raw SOPS document and the VM would mount a disk full of ciphertext — the
+  # failure is silent from the cluster's point of view (the Secret applies fine), so the stanza is
+  # as load-bearing as the file itself. Mirrors clusters/dev. `sops-age` is out-of-band (name only).
+  - patch: |-
+      apiVersion: kustomize.toolkit.fluxcd.io/v1
+      kind: Kustomization
+      metadata:
+        name: apps-vms
+        namespace: flux-system
+      spec:
+        decryption:
+          provider: sops
+          secretRef:
+            name: sops-age
  # --- GitOps source (operator decision 2026-09-01: prod tracks the SAME BRANCH as dev) ---
  #
  # ############################################################################################
@@ -203,7 +220,38 @@ patches:
        # Verified before the switch: a throwaway pod INSIDE prod resolved this host through
        # in-cluster CoreDNS to the Gateway VIP and cloned over the public LE cert with no CA
        # supplied. The workstation being able to reach it proves nothing about pod egress.
-        url: https://gitea.prod.home.keithjackson.dev/Home-Network/home-network-k3s-impl.git
+        # MOVED WITH THE APEX FLIP (2026-09-13) — and it had to move in the SAME fetch.
+        # This URL is a hardcoded literal, NOT templated on ${BASE_DOMAIN}, so the flip did not
+        # carry it. But the flip DOES rename prod's own HTTPRoute hostnames, so:
+        #   - external-dns (policy=sync) deletes gitea.prod.home.keithjackson.dev, and
+        #   - platform/coredns/coredns-custom.yaml answers the whole ${BASE_DOMAIN} zone with
+        #     ${GATEWAY_VIP}, so in-cluster resolution moves from prod.home. to home.
+        # Leaving this on the old name would therefore have severed prod from its OWN GitOps
+        # source moments after the flip reconciled — self-reference, the same class of trap as
+        # patching this url live and having the root Kustomization revert it. The fix has to land
+        # THROUGH THE OLD SOURCE, which is why it is in the same push as the flip rather than
+        # after it.
+        # FOLLOW-UP worth doing: point this at the in-cluster Service
+        # (gitea-http.gitea.svc.cluster.local) so prod's GitOps stops depending on public DNS and
+        # on its own Gateway at all. Deferred: it needs the TLS/credential path rethought.
+        # IN-CLUSTER SERVICE, NOT A PUBLIC HOSTNAME (2026-09-13). This is the durable fix for a
+        # deadlock the apex flip walked straight into, and it is worth stating precisely.
+        #
+        # The url used to be a public name. The flip renamed prod's HTTPRoute hostnames, so the
+        # name this GitRepository pointed at stopped serving — but the HTTPRoute that WOULD have
+        # served the new name lives in a DOWNSTREAM tier, which cannot reconcile while the source
+        # is broken. Source down -> routes never rename -> source stays down. Observed live:
+        # `srcReady=False`, "unable to list remote for https://gitea.home.keithjackson.dev".
+        #
+        # Pointing at the Service breaks the cycle permanently: prod's GitOps no longer depends on
+        # public DNS, on Cloudflare, on its own Gateway, or on ${BASE_DOMAIN} at all. A future
+        # domain change cannot sever prod from its own source again.
+        #
+        # Plain http is deliberate and safe here: it is cluster-internal traffic to a ClusterIP,
+        # TLS terminates at the Gateway for external clients only, the GitRepository has no
+        # secretRef (the repo is cloned anonymously), and every secret in the tree is SOPS-encrypted
+        # at rest regardless of transport.
+        url: http://gitea.gitea.svc.cluster.local:3000/Home-Network/home-network-k3s-impl.git
        ref:
          branch: main
  - target:
@@ -247,7 +295,24 @@ patches:
      # trusts a different Keycloak than the one prod actually runs.
      - op: replace
        path: /data/BASE_DOMAIN
-        value: "prod.home.keithjackson.dev"
+        # APEX AS OF 2026-09-13. Prod now serves home.keithjackson.dev directly; dev has been
+        # decommissioned and released the name. Prerequisites completed and VERIFIED before this
+        # flip, in this order:
+        #   1. dev's 18 A records released by its own external-dns (policy=sync, sources deleted)
+        #   2. dev's 18 LEGACY UNPREFIXED TXT registry entries deleted from Cloudflare by hand —
+        #      external-dns v0.21.0 removed only the `a-` prefixed form and then reported "All
+        #      records are already up to date", so it would NEVER have cleared them. They carried
+        #      `owner=default`, and prod runs `owner=prod`, so prod could not have claimed these
+        #      names while they existed. Confirmed gone at the AUTHORITY (betty.ns.cloudflare.com);
+        #      1.1.1.1 served stale cache for minutes afterwards and must not be trusted here.
+        #   3. dev's `*.home.keithjackson.dev` + apex Certificate deleted, so it stops renewing.
+        #      It was issued ~18d ago, so prod's request is #1 this week against LE's duplicate
+        #      limit of 5 per identical name set per week.
+        # NOTE the zone has wildcards `*.keithjackson.dev` AND `*.home.keithjackson.dev` pointing
+        # at the public IP 136.51.115.252 (legacy non-k3s prod). Dev's specific records were
+        # SHADOWING that wildcard; prod's new specific records shadow it again. The legacy stack
+        # lives on `*.keithjackson.dev` and is untouched by any of this.
+        value: "home.keithjackson.dev"
      # SAFETY NET #2 (independent of the owner id below): narrow ExternalDNS's name scope to prod's
      # OWN subtree, so prod cannot create, update or delete any record outside it no matter what the
      # TXT registry says. VERIFY ON FIRST RECONCILE — the Cloudflare provider uses this value for
@@ -301,8 +366,16 @@ patches:
      # Size-cap below the 50Gi PVC (headroom for WAL + head + compaction scratch): prod may hit the
      # size cap before 30d if series volume is high, keeping the disk from filling either way.
      - op: replace
+      # LOWERED 45GiB -> 36GiB on 2026-09-13. 45 of 50Gi left only 5 GiB, which is not headroom for
+      # what the comment above already names: retentionSize counts ONLY persisted blocks, not the WAL,
+      # not the head's in-flight segments, and not compaction scratch, and a large compaction can need
+      # roughly the size of the blocks being merged. At 90% one bad compaction is ENOSPC, and ENOSPC on
+      # /prometheus wedges every WAL commit: scrapes keep succeeding, nothing is stored, and every
+      # absent()/==0 alert in the platform fires falsely at once. Costs NO history: the TSDB is 11.2 GiB
+      # at 30d today, so 36GiB is ~3x current and 30d stays the binding limit. To keep more history,
+      # grow the PVC rather than the fraction of it.
        path: /data/MONITORING_PROMETHEUS_RETENTION_SIZE
-        value: "45GiB"
+        value: "36GiB"
      - op: replace
        path: /data/MONITORING_LOKI_PVC_SIZE
        value: "50Gi"
@@ -392,6 +465,23 @@ patches:
      - op: replace
        path: /data/CRAFTY_L4_VIP
        value: "192.168.2.22"
+      # PiHole's DNS listener VIP — udp/53 + tcp/53 for LAN clients (apps/wave-0/pihole-dns.yaml).
+      # 192.168.2.23 is the NEXT FREE address in the prod pool 192.168.2.20-.30, verified live
+      # 2026-09-14: the CiliumLoadBalancerIPPool `default-pool` reported IPsTotal 11 / IPsUsed 3 /
+      # IPsAvailable 8, and the only three allocations are .20 (cilium-gateway-shared), .21
+      # (unifi-l4-tcp/-udp) and .22 (crafty-l4-tcp/-udp). ARP-probed from a LAN host in the same
+      # broadcast domain (arping 192.168.2.23, 3 probes, 0 responses), so nothing off-cluster holds
+      # it either, and it is inside the pool block the operator already asserted sits outside the
+      # SOHO router's DHCP scope.
+      - op: replace
+        path: /data/PIHOLE_DNS_VIP
+        value: "192.168.2.23"
+      # The prod flat LAN. This is the 192.168.2.0/24 segment the SOHO ROUTER at 192.168.2.1 owns —
+      # NOT pfSense's 192.168.1.0/24, which is a different network and not in the LAN-DNS path.
+      # It scopes the ingress allow for PiHole's DNS listener to LAN clients only.
+      - op: replace
+        path: /data/LAN_CIDR
+        value: "192.168.2.0/24"
      # ------------------------------------------------------------------------------------------
      # BULK (EXTERNAL NFS) STORAGE HOST — *** NOT YET DECIDED. THIS PLACEHOLDER IS LOAD-BEARING. ***
      # ------------------------------------------------------------------------------------------
@@ -1,5 +1,19 @@
 # conformance/ — the home-k3s conformance harness (WS-TEST)

+> **STATUS NOTE (2026-09-29) — read before trusting the "Phase 0" framing below.**
+> This document speaks as though no cluster exists and the platform is scaffolding. **A
+> three-node k3s cluster has existed for weeks** and Flux has been reconciling against it.
+> Gitea is live, the Actions runner `incluster-dind` is online, and `main` is a protected
+> branch. Where the text says "Phase 0", "stub", or "no cluster exists", read it as
+> describing a **live gap** rather than an expected stage — most importantly, L2/L3
+> conformance still does not run in CI (`vars.CLUSTER_AVAILABLE` is unset), which is a real
+> coverage hole, not a phase.
+>
+> This mismatch is not cosmetic. A month of "the gate enforces this" claims rested on
+> documentation rather than measurement, and `main` was unprotected with zero runners
+> registered the whole time. **Query the live API before asserting platform state.**
+
+
 This subtree is the **definition of "done"** for the whole platform. Nothing is accepted
 on a demo, a screenshot, or "it reconciled": every requirement is proven by an
 **automated, reproducible, behavior-based test** tagged with the requirement ID(s) it
@@ -23,6 +37,9 @@ behavioral / L3 fault-injection** (this harness).
 ./run.sh --strict-coverage            # hygiene gate: fail on tag/annotation drift
 ./run.sh --require-all                # phase-exit gate: every requirement must be covered
 ./run.sh --record                     # run AND capture the evidence (see "Proof of pass")
+./run.sh --layer l0 --include-scope whole-repo   # union: the tagged subset PLUS every test
+                                      #   declaring `conformance.home.k3s/scope: whole-repo`
+./run.sh --layer l0 --print-selection # print the dirs the selection resolves to; run nothing
 ```

 **Gating is scoped, not "all 51 always"** (R-TEST-03). Three distinct checks:
@@ -32,6 +49,29 @@ behavioral / L3 fault-injection** (this harness).
 - `--requirements R-…` — **merge gate**: selects the tagged tests to run **and** asserts
  those touched requirements are covered (a listed safety-critical one must have an L3 test).
 - `--require-all` — **phase-exit gate**: every registry requirement must be covered.
+- `--include-scope whole-repo` — **the escape hatch scoping needs**, because scoping has one
+  blind spot and it is the worst-shaped kind. Some L0 invariants quantify over the WHOLE
+  tracked tree (no plaintext secrets anywhere; no RBAC wildcard anywhere), or over subtrees
+  the coarse path→requirement map keys to **nothing** (`apps/`, `infra/`, most of
+  `platform/`). For those, *the change most likely to break the invariant attributes no
+  requirement at all*, so requirement-scoped selection filters the check out of exactly that
+  change. Such a test **declares** its scope:
+
+  ```yaml
+  metadata:
+    annotations:
+      conformance.home.k3s/scope: "whole-repo"
+  ```
+
+  and `--include-scope whole-repo` unions every declaring test into the selection. The CI
+  stages (`ci/l0.sh`, `ci/l1.sh`, `ci/conformance.sh`) all pass it, so **adding the
+  annotation is the only step** — there is nothing to remember and nothing to hand-write.
+  Two consequences, both deliberate: a declaring test always runs, and a **SKIP of a
+  declaring test is UNWIRED, not green** (the runner exits 3, which `ci/l0.sh` turns into the
+  gate's own rc 3 — never a pass). `tests/l0-static/whole-repo-invariants-wired` proves the
+  mechanism end-to-end and falsifiably, so it cannot rot silently. This replaced a
+  hand-written "UNCONDITIONAL" stage per check in `ci/l0.sh`; see `lib/common.sh` for the
+  full rationale and the incidents behind it.
 - Documented out-of-scope gaps (e.g. `R-ENV-02` dev→prod promote and `R-GITOPS-01`
  state-in-git, owned by WS-INFRA/WS-GITOPS and keyed wholesale by the coarse path map)
  are exempted from the completeness gates via `--allow-gap`, wired in `run.sh` as
@@ -1,5 +1,19 @@
 # In-cluster conformance Job (L2/L3)

+> **STATUS NOTE (2026-09-29) — read before trusting the "Phase 0" framing below.**
+> This document speaks as though no cluster exists and the platform is scaffolding. **A
+> three-node k3s cluster has existed for weeks** and Flux has been reconciling against it.
+> Gitea is live, the Actions runner `incluster-dind` is online, and `main` is a protected
+> branch. Where the text says "Phase 0", "stub", or "no cluster exists", read it as
+> describing a **live gap** rather than an expected stage — most importantly, L2/L3
+> conformance still does not run in CI (`vars.CLUSTER_AVAILABLE` is unset), which is a real
+> coverage hole, not a phase.
+>
+> This mismatch is not cosmetic. A month of "the gate enforces this" claims rested on
+> documentation rather than measurement, and `main` was unprotected with zero runners
+> registered the whole time. **Query the live API before asserting platform state.**
+
+
 Per **ADR-0011** and **docs/14 "Where each layer runs"**: L0/L1 run in CI without a
 cluster, but **L2 behavioral and L3 fault-injection run as an in-cluster Chainsaw Job**
 on the dev/test cluster that **CI triggers and waits for**. CI holds **no** cluster
@@ -0,0 +1,14 @@
+# Reconciled by clusters/base/conformance.yaml (non-gating, wait:false).
+#
+# RBAC ONLY. chainsaw-job.yaml is deliberately NOT listed: that manifest is a TEMPLATE the CI
+# trigger renders and submits per run (with the commit SHA and the touched --requirements). Flux
+# reconciling it would create a permanent Job object and fight the trigger for ownership.
+#
+# The identities here are inert without
+# platform/kyverno/admission/conformance-trigger-job-shape.yaml, which is what actually bounds
+# the trigger to the committed run shape. RBAC is the necessary half, that policy the sufficient
+# half — see the header of rbac.yaml.
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - rbac.yaml
@@ -174,3 +174,68 @@ subjects:
  - kind: ServiceAccount
    name: conformance-runner
    namespace: conformance
+---
+# =============================================================================
+# THE TRIGGER IDENTITY — deliberately NOT conformance-runner.
+#
+# THE ESCALATION THIS EXISTS TO CLOSE (docs/plans/l2-l3-conformance-ci-wiring.md §4):
+# Kubernetes places NO `use` check on a Pod/Job's `serviceAccountName`. So any principal
+# that can `create jobs` in this namespace can create a Job with
+# `serviceAccountName: conformance-runner` and an ARBITRARY command — i.e. run arbitrary
+# code with the runner's privileges (nodes/patch, pods/exec, namespaces/patch, jobs).
+# A CI-held token with plain `create jobs` therefore IS the privileged identity, no matter
+# how narrow its own RBAC looks. That would break R-SEC-02 ("CI holds no broad cluster
+# access") while appearing to satisfy it.
+#
+# RBAC ALONE CANNOT FIX THIS. The real boundary is the admission policy
+# platform/kyverno/admission/conformance-trigger-job-shape.yaml, which admits Jobs from
+# THIS ServiceAccount only when they match the committed conformance shape. This Role is
+# the necessary half; that policy is the sufficient half. Neither works alone — do not
+# grant this Role without that policy reconciled and ENFORCING.
+#
+# Namespaced Role, bound only in `conformance`. No ClusterRole, deliberately.
+# =============================================================================
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: conformance-trigger
+  namespace: conformance
+  labels:
+    app.kubernetes.io/part-of: conformance
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: conformance-trigger
+  namespace: conformance
+  labels:
+    app.kubernetes.io/part-of: conformance
+rules:
+  # Create the run, and watch it to completion.
+  - apiGroups: [batch]
+    resources: [jobs]
+    verbs: [create, get, list, watch]
+  # Read the Job's pod and its log — this is how results come back. Deliberately NOT
+  # pods/exec and NOT `kubectl cp`: the run tars its artifacts to stdout and CI decodes
+  # them from the log, so no execution channel into the runner pod is ever granted.
+  - apiGroups: [""]
+    resources: [pods, pods/log]
+    verbs: [get, list, watch]
+  # NOTHING ELSE. In particular NO delete on jobs (a trigger that can delete can hide a
+  # failed run), no secrets, no configmaps, no exec, no create on pods.
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: conformance-trigger
+  namespace: conformance
+  labels:
+    app.kubernetes.io/part-of: conformance
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: conformance-trigger
+subjects:
+  - kind: ServiceAccount
+    name: conformance-trigger
+    namespace: conformance
@@ -47,6 +47,62 @@ conf_dirs_for_requirements() {
  done < <(conf_all_test_files) | sort -u
 }

+# --- DECLARED SCOPE: whole-repo invariants -------------------------------------------
+# A test may also declare the SCOPE of the invariant it asserts:
+#
+#     metadata:
+#       annotations:
+#         conformance.home.k3s/scope: "whole-repo"
+#
+# WHY THIS EXISTS — the requirement-scoped-selection blind spot (R-TEST-03)
+# ------------------------------------------------------------------------
+# The merge gate runs the conformance subset tagged with the requirements a change
+# TOUCHES (ci/touched-requirements.sh -> `--requirements`). That is right for an invariant
+# whose input surface is the subtree its requirements map to. It is WRONG — silently, and in
+# the worst direction — for an invariant that quantifies over the WHOLE tracked tree, or over
+# subtrees (apps/, platform/<most>, infra/) that the coarse path->requirement map keys to
+# NOTHING. For those, the change most likely to break the invariant attributes no requirement
+# at all, so the requirement-scoped selection filters the check out of EXACTLY that change.
+# Three real incidents came out of that blind spot; each is recorded in the header of the
+# test that now guards it (flux-postbuild-substitution, keycloak-client-secret-reconciler,
+# bulk-tier-distinct-from-replicated).
+#
+# The repo's previous answer was a hand-written "UNCONDITIONAL" stage per such test in
+# ci/l0.sh — which does not scale and fails silently in the worst way: whoever adds the NEXT
+# whole-repo invariant must REMEMBER to hand-write a stage, and if they forget, the check runs
+# only when some unrelated requirement happens to be touched. The scope annotation replaces
+# that with a DECLARATION the runner enforces: `run.sh --include-scope whole-repo` unions
+# every test carrying it into the selection, so adding the annotation is the only step.
+#
+# TWO things follow from the annotation, and both are deliberate:
+#   1. the test is ALWAYS selected (union with the requirement-scoped subset), and
+#   2. a SKIP of that test is UNWIRED, NOT GREEN (lib/run_l1_offline.py --unwired-scope).
+#      A whole-repo invariant that reports "nothing to audit" is reporting that the subtree
+#      it audits has VANISHED, which is not a pass. This is the rc-3 semantics the bespoke
+#      stages encoded ("check SKIPPED (clusters/ absent) — not a pass"), preserved verbatim.
+export CONF_SCOPE_ANNOTATION="${CONF_LABEL_PREFIX}/scope"
+
+# Directories of tests DECLARING the given scope (e.g. "whole-repo"). The annotation is
+# matched on a real YAML mapping line only: a `#` comment cannot start with the key, so a
+# scope named in a test's header prose is documentation, not a declaration (the same
+# "reference, not declaration" rule ci/touched-requirements.sh applies to R-IDs).
+conf_dirs_for_scope() {
+  local scope="$1" f
+  [ -n "$scope" ] || return 0
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    if grep -Eq "^[[:space:]]*${CONF_SCOPE_ANNOTATION}:[[:space:]]*[\"']?${scope}[\"']?[[:space:]]*$" "$f"; then
+      dirname "$f"
+    fi
+  done < <(conf_all_test_files) | sort -u
+}
+
+# Union of conf_dirs_for_scope over a comma/space separated list of scopes.
+conf_dirs_for_scopes() {
+  local scopes="$1" s
+  for s in ${scopes//,/ }; do conf_dirs_for_scope "$s"; done | sort -u
+}
+
 # Directories for a given layer (subtree): l0 | l1 | l2 | l3 | meta | all.
 # Accepts a comma/space separated LIST of layers (e.g. "l2,l3") and returns the UNION of
 # their test dirs, deduplicated. A single layer keeps its prior behavior (backward compatible);
@@ -467,7 +467,14 @@ def git_sha(repo: Path) -> str:
                             capture_output=True, text=True, check=True).stdout.strip()
    except (subprocess.CalledProcessError, OSError):
        return "unknown"
-    dirty = subprocess.run(["git", "-C", str(repo), "diff", "--quiet", "HEAD", "--"],
+    # EXCLUDE conformance/runs/. It is TRACKED, so `--record` writing ledger.jsonl dirtied the
+    # tree and every LATER run in the same session was stamped `-dirty` — recording one test
+    # poisoned the next, and check.sh refuses to honour a dirty proven row. That cost a second
+    # live fault-injection run on prod to work around. The docstring above already states the
+    # intent for the untracked runs/<id>/ half of this same artifact; the ledger is the tracked
+    # half. Mirrors status.py's IMPL_EXCLUDE_PREFIXES, which lists this path for the same reason.
+    dirty = subprocess.run(["git", "-C", str(repo), "diff", "--quiet", "HEAD", "--",
+                            ".", ":(exclude)conformance/runs/"],
                           capture_output=True).returncode != 0
    return f"{sha}-dirty" if dirty else sha

@@ -482,6 +489,36 @@ def pinned_chainsaw_version(conf_root: Path) -> str:
    return "unknown"


+def context_env() -> str:
+    """The env a run TARGETED, derived from the live kube context — never guessed.
+
+    WHY THIS IS NOT A DEFAULT STRING. `--env` used to fall back to the literal "dev"
+    (`os.environ.get("CONF_ENV", "dev")`), and CONF_ENV is set nowhere in this repo, so EVERY
+    recorded proof was stamped `env: dev` regardless of the cluster it ran against. That was
+    harmless while dev was the only cluster. Dev was decommissioned 2026-09-12 and prod is now
+    the only one, so on 2026-09-13 a genuine prod DR-restore proof was recorded as `env: dev` —
+    a proof that lies about where it was proven is worse than no proof, because the ledger's
+    whole purpose is to say what was demonstrated WHERE. Caught before it was committed.
+
+    Derived from `kubectl config current-context` (`k3s-prod` -> `prod`), which cannot drift
+    from the cluster the run actually talked to. Undeterminable is "unknown", NEVER a cluster
+    name: an unreadable context must not silently attribute a proof to an environment.
+    """
+    try:
+        p = subprocess.run(["kubectl", "config", "current-context"],
+                           capture_output=True, text=True, timeout=15)
+    except (OSError, subprocess.TimeoutExpired):
+        return "unknown"
+    if p.returncode != 0:
+        return "unknown"
+    ctx = (p.stdout or "").strip()
+    if not ctx:
+        return "unknown"
+    # contexts in this repo are named k3s-<env>; anything else is recorded verbatim so an
+    # unexpected context is visible in the ledger rather than being coerced into a known name.
+    return ctx[len("k3s-"):] if ctx.startswith("k3s-") else ctx
+
+
 def server_kube_version() -> str:
    """Server gitVersion via `kubectl version` (read-only), else "unknown"."""
    for args in (["kubectl", "version", "-o", "json"],
@@ -876,7 +913,9 @@ def main() -> int:
                    help=f"append-only ledger (default {DEFAULT_LEDGER})")
    ap.add_argument("--tests", type=Path, default=CONF_ROOT / "tests")
    ap.add_argument("--repo", type=Path, default=REPO_ROOT)
-    ap.add_argument("--env", default=os.environ.get("CONF_ENV", "dev"))
+    ap.add_argument("--env", default=os.environ.get("CONF_ENV") or context_env(),
+                    help="env the run targeted; derived from the kube context when "
+                         "unset (never defaulted to a cluster name)")
    ap.add_argument("--chainsaw-version", default=None,
                    help="override the versions.env pin (recorded verbatim)")
    ap.add_argument("--kube-version", default=os.environ.get("CONF_KUBE_VERSION"),
@@ -19,6 +19,30 @@ Exit 0 iff every selected offline check passes.

 The per-dir check script is whichever of `render-check.sh` / `check.sh` the directory
 carries; a dir with neither is reported SKIPPED (never a pass).
+
+DECLARED SCOPE, AND WHY A SKIP IS NOT ALWAYS HARMLESS (--unwired-scope)
+----------------------------------------------------------------------
+Exit 0 here means "every selected check passed"; a check that exits 3 is SKIPPED and, by
+default, does not fail the run (a scaffold with no check script, an audit whose subject
+subtree does not exist yet). That default is WRONG for a WHOLE-REPO invariant. Those are the
+checks ci/l0.sh used to run as hand-written "UNCONDITIONAL" stages, and each of those stages
+mapped rc 3 to the GATE's rc 3 with the words "not a pass":
+
+    3) skip "substitution check SKIPPED (clusters/ absent) — not a pass"
+       summary "- subst-safety: **SKIPPED** (nothing to audit)"
+       if [ "$rc" -eq 0 ]; then rc=3; fi
+
+A whole-repo check reporting "nothing to audit" is reporting that the tree it audits has
+VANISHED — which is a louder problem than the check failing, not a quieter one. So:
+
+  --unwired-scope SCOPE   a test DECLARING `<prefix>/scope: SCOPE` whose check SKIPS (rc 3,
+                          or no check script at all) makes this runner exit 3 instead of 0.
+                          Hard failures still win (exit 1); rc 3 never masks one.
+
+Exit codes: 0 all selected checks passed / 1 at least one FAILED / 3 nothing failed but a
+scope-declared check was UNWIRED. conformance/run.sh propagates 3 verbatim; ci/l0.sh turns it
+into the gate's own rc 3. This is the ONE place the "unwired, not green" rule lives now,
+instead of once per hand-written stage.
 """
 from __future__ import annotations

@@ -36,6 +60,24 @@ LABEL_LINE_RE_TMPL = r"^\s*{prefix}/(R-[A-Z0-9]+-[0-9]+)\s*:\s*[\"']?true"
 CHECK_SCRIPTS = ("render-check.sh", "check.sh")


+def scope_of(test_yaml: Path, annotation: str) -> str:
+    """The scope a test DECLARES, or "" when it declares none.
+
+    Matched on a real YAML mapping line: a `#` comment cannot begin with the annotation key,
+    so a scope named in the test's header prose is documentation, not a declaration — the
+    same "reference, not declaration" rule ci/touched-requirements.sh applies to R-IDs.
+    Mirrors conf_dirs_for_scope() in lib/common.sh; they must agree.
+    """
+    if not test_yaml.exists():
+        return ""
+    rx = re.compile(r"^\s*" + re.escape(annotation) + r"\s*:\s*[\"']?([A-Za-z0-9_.-]+)[\"']?\s*$")
+    for line in test_yaml.read_text().splitlines():
+        m = rx.match(line)
+        if m:
+            return m.group(1)
+    return ""
+
+
 def layer_of(d: Path) -> str:
    """Layer for the JUnit properties, from the subtree the test lives in."""
    rel = str(d)
@@ -59,25 +101,38 @@ def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--junit", type=Path, required=True)
    ap.add_argument("--label-prefix", default="conformance.home.k3s")
+    ap.add_argument("--scope-annotation", default="conformance.home.k3s/scope",
+                    help="annotation key a test uses to DECLARE its invariant's scope")
+    ap.add_argument("--unwired-scope", action="append", default=[], metavar="SCOPE",
+                    help="a test declaring this scope that SKIPS is UNWIRED, not green "
+                         "(makes this runner exit 3); repeatable")
+    ap.add_argument("--summary-out", type=Path, default=None,
+                    help="write one Markdown line per case here, for the CI step summary")
    ap.add_argument("dirs", nargs="+", type=Path)
    args = ap.parse_args()

-    cases = []  # (name, reqs, dir, rc, output)
+    strict_scopes = set(args.unwired_scope)
+
+    cases = []  # (name, reqs, dir, rc, output, scope)
    for d in args.dirs:
        check = next((d / s for s in CHECK_SCRIPTS if (d / s).exists()), None)
        name, reqs = collect_meta(d / "chainsaw-test.yaml", args.label_prefix)
+        scope = scope_of(d / "chainsaw-test.yaml", args.scope_annotation)
        if check is None:
            cases.append((name, reqs, d, 3,
-                          f"no offline check script ({' or '.join(CHECK_SCRIPTS)}) in {d}"))
+                          f"no offline check script ({' or '.join(CHECK_SCRIPTS)}) in {d}",
+                          scope))
            continue
        proc = subprocess.run(
            ["bash", str(check)], capture_output=True, text=True
        )
        out = (proc.stdout + proc.stderr).strip()
-        cases.append((name, reqs, d, proc.returncode, out))
+        cases.append((name, reqs, d, proc.returncode, out, scope))

    failures = sum(1 for c in cases if c[3] not in (0, 3))
    skipped = sum(1 for c in cases if c[3] == 3)
+    # A SKIP of a scope-declared check is UNWIRED, not green (see the module docstring).
+    unwired = [c for c in cases if c[3] == 3 and c[5] in strict_scopes]

    suite = ET.Element(
        "testsuite",
@@ -89,7 +144,8 @@ def main() -> int:
            "skipped": str(skipped),
        },
    )
-    for name, reqs, d, rc, out in cases:
+    summary_lines = []
+    for name, reqs, d, rc, out, scope in cases:
        tc = ET.SubElement(
            suite,
            "testcase",
@@ -100,17 +156,33 @@ def main() -> int:
        ET.SubElement(props, "property", {"name": "requirements", "value": ",".join(reqs)})
        ET.SubElement(props, "property", {"name": "layer", "value": layer_of(d)})
        ET.SubElement(props, "property", {"name": "path", "value": str(d)})
+        ET.SubElement(props, "property", {"name": "scope", "value": scope})
        if rc == 3:
            ET.SubElement(tc, "skipped", {"message": out or "no offline check script"})
        elif rc != 0:
            fail = ET.SubElement(tc, "failure", {"message": f"offline check exit {rc}"})
            fail.text = out
        status = "PASS" if rc == 0 else ("SKIP" if rc == 3 else "FAIL")
+        mark = f" scope={scope}" if scope else ""
        print(f"[offline] {layer_of(d):3s} {status:4s} {name} "
-              f"({','.join(reqs) or 'untagged'})",
+              f"({','.join(reqs) or 'untagged'}){mark}",
              file=sys.stderr)
        if rc not in (0, 3):
            print(out, file=sys.stderr)
+        # One step-summary line per case, naming what ran — the generated replacement for the
+        # hand-written `summary "- subst-safety: **passed**"` line each deleted stage carried.
+        tag = f" ({scope})" if scope else ""
+        if rc == 0:
+            verdict = "**passed**"
+        elif rc == 3:
+            verdict = ("**SKIPPED** (UNWIRED, not green)" if scope in strict_scopes
+                       else "**SKIPPED** (nothing to audit)")
+        else:
+            verdict = f"**FAILED** (exit {rc})"
+        summary_lines.append(f"- {layer_of(d).lower()}/{name}{tag}: {verdict}")
+        if rc == 3 and scope in strict_scopes:
+            print(f"[offline] {name}: SKIPPED, and it declares scope={scope!r} — "
+                  f"UNWIRED, NOT GREEN. {out}", file=sys.stderr)

    root = ET.Element(
        "testsuites",
@@ -126,9 +198,19 @@ def main() -> int:
    args.junit.parent.mkdir(parents=True, exist_ok=True)
    xml = minidom.parseString(ET.tostring(root, "utf-8")).toprettyxml(indent="  ")
    args.junit.write_text(xml)
-    print(f"[offline] wrote JUnit ({len(cases)} case(s), {failures} failure(s)) -> "
-          f"{args.junit}", file=sys.stderr)
-    return 1 if failures else 0
+    if args.summary_out is not None:
+        args.summary_out.parent.mkdir(parents=True, exist_ok=True)
+        args.summary_out.write_text("\n".join(summary_lines) + ("\n" if summary_lines else ""))
+
+    print(f"[offline] wrote JUnit ({len(cases)} case(s), {failures} failure(s), "
+          f"{skipped} skip(s), {len(unwired)} unwired) -> {args.junit}", file=sys.stderr)
+    if failures:
+        return 1
+    if unwired:
+        print("[offline] UNWIRED (declared scope, SKIPPED — not a pass): "
+              + ", ".join(c[0] for c in unwired), file=sys.stderr)
+        return 3
+    return 0


 if __name__ == "__main__":
@@ -10,6 +10,12 @@
 #   ./run.sh --requirements R-NET-01,R-NET-06   # merge-gate subset (tagged)
 #   ./run.sh --layer l2               # one layer (l0|l1|l2|l3|meta|all; l0/l1 need no cluster)
 #   ./run.sh --requirements R-NET-01,R-NET-02 --layer l2   # intersect: tagged AND in layer
+#   ./run.sh --layer l0 --requirements R-X --include-scope whole-repo
+#                                     # UNION: the tagged subset PLUS every test that
+#                                     #   DECLARES `conformance.home.k3s/scope: whole-repo`.
+#                                     #   A whole-repo invariant must run on EVERY gate
+#                                     #   invocation — see lib/common.sh's scope block for
+#                                     #   why, and why a SKIP of one is exit 3, not green.
 #   ./run.sh --coverage-only          # regenerate coverage report only (no cluster)
 #   ./run.sh --status                 # DERIVED STATUS report only (no cluster): per
 #                                     #   requirement, is it implemented, is it actually
@@ -18,6 +24,11 @@
 #                                     #   (runs/ledger.jsonl) actually proves it — see
 #                                     #   lib/status.py. No ledger row => not-derivable.
 #   ./run.sh --lint                   # structural-validate test defs (no cluster)
+#   ./run.sh --print-selection        # print the test dirs the CURRENT selection resolves
+#                                     #   to, one per line, and exit. Runs no check. This is
+#                                     #   how a test can PROVE the selection includes it
+#                                     #   (tests/l0-static/whole-repo-invariants-wired) without
+#                                     #   executing the suite and recursing into itself.
 #   ./run.sh --strict-coverage        # hygiene gate: fail on tag/annotation drift
 #   ./run.sh --requirements R-NET-01  # ALSO asserts those IDs are covered (merge gate)
 #   ./run.sh --require-all            # phase-exit: every requirement must be covered
@@ -79,6 +90,7 @@ ORIG_ARGS=("$@")

 LAYER="all"
 REQS=""
+INCLUDE_SCOPES=""   # --include-scope: scopes unioned into the selection (see lib/common.sh)
 MODE="run"          # run | coverage-only | status | lint
 STRICT_COVERAGE=0
 REQUIRE_ALL=0
@@ -122,9 +134,11 @@ while [ $# -gt 0 ]; do
  case "$1" in
    --layer)          LAYER="$2"; shift 2 ;;
    --requirements)   REQS="$(conf_normalize_reqs "$2")"; shift 2 ;;
+    --include-scope)  INCLUDE_SCOPES="${INCLUDE_SCOPES:+${INCLUDE_SCOPES},}$2"; shift 2 ;;
    --coverage-only)  MODE="coverage-only"; shift ;;
    --status)         MODE="status"; shift ;;
    --lint)           MODE="lint"; shift ;;
+    --print-selection) MODE="print-selection"; shift ;;
    --strict-coverage) STRICT_COVERAGE=1; shift ;;
    --require-all)    REQUIRE_ALL=1; shift ;;
    --no-cluster)     FORCE_NO_CLUSTER=1; shift ;;
@@ -187,7 +201,7 @@ if [ "${RECORD}" = 1 ] && [ -z "${CONF_RECORD_CHILD:-}" ]; then
  # CONF_LEDGER exists so the harness's own tests can exercise this path without writing
  # to the real ledger; operators should never set it.
  "${PYTHON}" "${CONF_ROOT}/lib/record_run.py" \
-    --run-dir "${RUN_DIR}" --env "${CONF_ENV:-dev}" \
+    --run-dir "${RUN_DIR}" ${CONF_ENV:+--env "$CONF_ENV"} \
    --ledger "${CONF_LEDGER:-${CONF_ROOT}/runs/ledger.jsonl}" || true
  log "RECORD: run rc=${RUN_RC}. Commit conformance/runs/${RUN_ID}/ WITH its run.log and"
  log "RECORD: conformance/runs/ledger.jsonl — an uncommitted ledger proves nothing."
@@ -225,7 +239,7 @@ gen_status() {
    --registry "${CONF_ROOT}/requirements/registry.yaml" \
    --tests "${CONF_ROOT}/tests" \
    --out "${STATUS_OUT}" \
-    --env "${CONF_ENV:-dev}" \
+    ${CONF_ENV:+--env "$CONF_ENV"} \
    "$@"
 }

@@ -251,11 +265,38 @@ lint_tests() {
 }

 # --- Select which test directories Chainsaw should run --------------------------------
+# Requirement-scoped selection, then the DECLARED-SCOPE union on top:
+#
+#   (--requirements ∩ --layer)  ∪  (--include-scope ∩ --layer)
+#
+# The left half is R-TEST-03's touched subset. The right half is the fix for its blind
+# spot: an invariant that quantifies over the whole tracked tree cannot be selected BY the
+# requirements a change touches, because the change most likely to break it touches none of
+# them. See lib/common.sh's scope block for the incidents. The union is fail-closed by
+# construction — it can only ADD tests to a run, never remove one.
 select_dirs() {
-  # --requirements AND --layer together => intersection (tests carrying the tag
-  # AND living in that layer subtree). Either alone keeps its prior meaning, so
-  # this is backward compatible (LAYER defaults to "all"). Both helpers emit
-  # sorted, de-duplicated dirs, so `comm -12` yields the intersection.
+  {
+    requirement_scoped_dirs
+    # The scope union is still LAYER-bounded: `--layer l0` must not pull a whole-repo-scoped
+    # L2 test into an offline run. With no --layer (all), nothing is bounded away.
+    if [ -n "${INCLUDE_SCOPES}" ]; then
+      if [ "${LAYER}" != all ]; then
+        comm -12 \
+          <(conf_dirs_for_scopes "${INCLUDE_SCOPES}") \
+          <(conf_dirs_for_layer "${LAYER}")
+      else
+        conf_dirs_for_scopes "${INCLUDE_SCOPES}"
+      fi
+    fi
+  } | sort -u
+}
+
+# The pre-existing requirement/layer selection, unchanged:
+# --requirements AND --layer together => intersection (tests carrying the tag
+# AND living in that layer subtree). Either alone keeps its prior meaning, so
+# this is backward compatible (LAYER defaults to "all"). Both helpers emit
+# sorted, de-duplicated dirs, so `comm -12` yields the intersection.
+requirement_scoped_dirs() {
  if [ -n "${REQS}" ] && [ "${LAYER}" != all ]; then
    comm -12 \
      <(conf_dirs_for_requirements "${REQS}") \
@@ -396,6 +437,12 @@ layers_are_offline_only() {
  return 0
 }

+# Markdown one-liner per executed offline check, for the CI step summary. Written next to
+# the JUnit; ci/l0.sh + ci/l1.sh splice it into $GITHUB_STEP_SUMMARY so the gate output still
+# NAMES every check that ran (that is what the deleted per-check gate stages did, one hard-coded
+# `summary` line each — now generated for all of them, whole-repo-scoped ones marked as such).
+: "${OFFLINE_SUMMARY_OUT:=${ARTIFACTS}/offline-summary.md}"
+
 run_offline_checks() {
  local -a dirs
  mapfile -t dirs < <(offline_selected_dirs)
@@ -403,14 +450,30 @@ run_offline_checks() {
    log "No L0/L1 offline checks match the selection (layer=${LAYER} reqs='${REQS}')."
    return 0
  fi
+  # Declared scopes are passed through so the runner knows WHICH cases must not be allowed to
+  # report a SKIP as green (rc 3). See lib/common.sh's scope block and run_l1_offline.py.
+  local -a scope_args=() s
+  for s in ${INCLUDE_SCOPES//,/ }; do scope_args+=(--unwired-scope "$s"); done
  log "Running ${#dirs[@]} offline L0/L1 check(s) (no cluster; docs/14)."
+  [ -n "${INCLUDE_SCOPES}" ] && log "  unconditional (declared scope ${INCLUDE_SCOPES}): $(conf_dirs_for_scopes "${INCLUDE_SCOPES}" | xargs -n1 basename 2>/dev/null | tr '\n' ' ')"
  "${PYTHON}" "${CONF_ROOT}/lib/run_l1_offline.py" \
-    --junit "${JUNIT_OUT}" --label-prefix "${CONF_LABEL_PREFIX}" "${dirs[@]}"
+    --junit "${JUNIT_OUT}" --label-prefix "${CONF_LABEL_PREFIX}" \
+    --scope-annotation "${CONF_SCOPE_ANNOTATION}" \
+    --summary-out "${OFFLINE_SUMMARY_OUT}" \
+    ${scope_args[@]+"${scope_args[@]}"} "${dirs[@]}"
 }

 ###############################################################################
 # Main
 ###############################################################################
+# --print-selection is deliberately handled FIRST: it resolves the selection and exits,
+# writing nothing and running no check. A test that asserts "the gate's selection cannot
+# filter me out" needs to ask that question without executing the suite it is part of.
+if [ "${MODE}" = "print-selection" ]; then
+  select_dirs
+  exit 0
+fi
+
 log "Coverage report first (always)"
 gen_coverage

@@ -440,17 +503,26 @@ esac
 # L0 static + L1 rendering are cluster-independent (docs/14): run the selected offline
 # checks and treat their result as authoritative REGARDLESS of cluster availability. An
 # offline check failure is a real failure (nothing cluster-gated about it), so it always blocks.
+# rc 3 is the harness-wide SKIPPED/not-run code (ci/README.md): NOT a pass, NOT a fail. The
+# offline runner returns it when a test carrying a --unwired-scope scope SKIPPED — a whole-repo
+# invariant reporting "nothing to audit" means the subtree it audits is gone, which the gate
+# must see as UNWIRED. It is propagated verbatim so ci/l0.sh can set the gate's own rc=3,
+# exactly as the deleted per-check stages did.
 OFFLINE_RC=0
 run_offline_checks || OFFLINE_RC=$?
 if layers_are_offline_only; then
  # Offline-only run (the ci/l0.sh + ci/l1.sh merge-gate paths): the offline result IS the result.
-  if [ "${OFFLINE_RC}" -eq 0 ]; then
-    log "Done (offline ${LAYER}). JUnit: ${JUNIT_OUT} | Coverage: ${COVERAGE_OUT}/coverage.md"
-  else
-    log "Offline ${LAYER} checks FAILED (rc=${OFFLINE_RC}). JUnit: ${JUNIT_OUT}"
-  fi
+  case "${OFFLINE_RC}" in
+    0) log "Done (offline ${LAYER}). JUnit: ${JUNIT_OUT} | Coverage: ${COVERAGE_OUT}/coverage.md" ;;
+    3) log "Offline ${LAYER}: a scope-declared check SKIPPED — UNWIRED, not green (rc=3). JUnit: ${JUNIT_OUT}" ;;
+    *) log "Offline ${LAYER} checks FAILED (rc=${OFFLINE_RC}). JUnit: ${JUNIT_OUT}" ;;
+  esac
  exit "${OFFLINE_RC}"
 fi
+if [ "${OFFLINE_RC}" -eq 3 ]; then
+  log "Offline L0/L1: a scope-declared check SKIPPED — UNWIRED, not green (rc=3)."
+  exit 3
+fi
 if [ "${OFFLINE_RC}" -ne 0 ]; then
  log "Offline L0/L1 checks FAILED (rc=${OFFLINE_RC}) — blocking (not cluster-gated)."
  exit "${OFFLINE_RC}"
@@ -0,0 +1,12 @@
+<?xml version="1.0" ?>
+<testsuites name="home-k3s-conformance" tests="1" failures="0" errors="0" skipped="0">
+  <testsuite name="home-k3s-conformance L0/L1 (offline)" tests="1" failures="0" errors="0" skipped="0">
+    <testcase classname="L1:R-NET-05,R-NET-06,R-NET-07" name="egress-class-render">
+      <properties>
+        <property name="requirements" value="R-NET-05,R-NET-06,R-NET-07"/>
+        <property name="layer" value="L1"/>
+        <property name="path" value="/work/.claude/conf-clone/conformance/tests/l1-rendering/egress-class-render"/>
+      </properties>
+    </testcase>
+  </testsuite>
+</testsuites>
@@ -0,0 +1,7 @@
+[1m[run.sh][0m Coverage report first (always)
+[coverage] 49/51 requirements have a scaffolded test (96.1%); 2 gap(s), 0 safety-critical gap(s).
+[coverage] wrote /work/.claude/conf-clone/conformance/_artifacts/coverage/coverage.md and /work/.claude/conf-clone/conformance/_artifacts/coverage/coverage.json
+[1m[run.sh][0m Running 1 offline L0/L1 check(s) (no cluster; docs/14).
+[offline] L1  PASS egress-class-render (R-NET-05,R-NET-06,R-NET-07)
+[offline] wrote JUnit (1 case(s), 0 failure(s)) -> /work/.claude/conf-clone/conformance/_artifacts/report.junit.xml
+[1m[run.sh][0m Done (offline l1). JUnit: /work/.claude/conf-clone/conformance/_artifacts/report.junit.xml | Coverage: /work/.claude/conf-clone/conformance/_artifacts/coverage/coverage.md
@@ -0,0 +1,4 @@
+<testsuites name="chainsaw-report" tests="1" failures="0" errors="0" time="0.000000"><testsuite name="/work/.claude/conf-clone/conformance/tests/l3-fault-injection/vpn-killswitch" tests="1" failures="0" errors="0" id="0" time="">
+    <testcase name="vpn-killswitch" classname="" time="174.632779" />
+  </testsuite>
+</testsuites>
@@ -0,0 +1,237 @@
+[1m[run.sh][0m Coverage report first (always)
+[coverage] 49/51 requirements have a scaffolded test (96.1%); 2 gap(s), 0 safety-critical gap(s).
+[coverage] wrote /work/.claude/conf-clone/conformance/_artifacts/coverage/coverage.md and /work/.claude/conf-clone/conformance/_artifacts/coverage/coverage.json
+[1m[run.sh][0m No L0/L1 offline checks match the selection (layer=l3 reqs='R-NET-06').
+[1m[run.sh][0m LIGHT pass: 1 test(s), parallel=2 (pinned v0.2.12)
+Version: 0.2.12
+Loading config (/work/.claude/conf-clone/conformance/config/chainsaw-config.yaml)...
+- Using test file: chainsaw-test
+- TestDirs [/work/.claude/conf-clone/conformance/tests/l3-fault-injection/vpn-killswitch]
+- SkipDelete false
+- FailFast false
+- ReportFormat 'JUNIT-TEST'
+- ReportName 'chainsaw-report-light'
+- ReportPath '/work/.claude/conf-clone/conformance/_artifacts'
+- Namespace ''
+- FullName false
+- IncludeTestRegex ''
+- ExcludeTestRegex ''
+- ApplyTimeout 1m30s
+- AssertTimeout 3m0s
+- CleanupTimeout 2m0s
+- DeleteTimeout 2m0s
+- ErrorTimeout 1m0s
+- ExecTimeout 3m0s
+- DeletionPropagationPolicy Background
+- Parallel 2
+- Template true
+- NoCluster false
+- PauseOnFailure false
+Loading tests...
+- vpn-killswitch (/work/.claude/conf-clone/conformance/tests/l3-fault-injection/vpn-killswitch)
+Loading values...
+Running tests...
+=== RUN   chainsaw
+=== PAUSE chainsaw
+=== CONT  chainsaw
+=== RUN   chainsaw/vpn-killswitch
+=== PAUSE chainsaw/vpn-killswitch
+=== CONT  chainsaw/vpn-killswitch
+    l.go:52: | 01:44:38 | [32;1mvpn-killswitch[0;22m | [32;1m@chainsaw                                [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | v1/Namespace @ chainsaw-credible-bird
+    l.go:52: | 01:44:38 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:44:38 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        kubectl label namespace "$NAMESPACE" \
+          pod-security.kubernetes.io/enforce=privileged \
+          pod-security.kubernetes.io/warn=privileged \
+          pod-security.kubernetes.io/audit=privileged \
+          --overwrite
+        echo "NS_PRIVILEGED_OK"
+    l.go:52: | 01:44:39 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        namespace/chainsaw-credible-bird labeled
+        NS_PRIVILEGED_OK
+    l.go:52: | 01:44:39 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:44:39 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mAPPLY[0;22m     | [36;1mRUN[0;22m   | v1/Pod @ chainsaw-credible-bird/egress-internet
+    l.go:52: | 01:44:39 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | v1/Pod @ chainsaw-credible-bird/egress-internet
+    l.go:52: | 01:44:39 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mAPPLY[0;22m     | [32;1mDONE[0;22m  | v1/Pod @ chainsaw-credible-bird/egress-internet
+    l.go:52: | 01:44:39 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mAPPLY[0;22m     | [36;1mRUN[0;22m   | v1/Pod @ chainsaw-credible-bird/egress-vpn
+    l.go:52: | 01:44:39 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | v1/Pod @ chainsaw-credible-bird/egress-vpn
+    l.go:52: | 01:44:39 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mAPPLY[0;22m     | [32;1mDONE[0;22m  | v1/Pod @ chainsaw-credible-bird/egress-vpn
+    l.go:52: | 01:44:39 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mASSERT[0;22m    | [36;1mRUN[0;22m   | v1/Pod @ chainsaw-credible-bird/egress-internet
+    l.go:52: | 01:44:41 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mASSERT[0;22m    | [32;1mDONE[0;22m  | v1/Pod @ chainsaw-credible-bird/egress-internet
+    l.go:52: | 01:44:41 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mASSERT[0;22m    | [36;1mRUN[0;22m   | v1/Pod @ chainsaw-credible-bird/egress-vpn
+    l.go:52: | 01:44:41 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mASSERT[0;22m    | [32;1mDONE[0;22m  | v1/Pod @ chainsaw-credible-bird/egress-vpn
+    l.go:52: | 01:44:41 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        ns="$NAMESPACE"
+        get_ip() {
+          kubectl -n "$ns" exec "$1" -c curl -- \
+            curl -fsS --max-time 10 https://api.ipify.org 2>/dev/null || true
+        }
+        wan="" vpn=""
+        for i in $(seq 1 12); do
+          [ -n "$wan" ] || wan="$(get_ip egress-internet)"
+          [ -n "$vpn" ] || vpn="$(get_ip egress-vpn)"
+          if [ -n "$wan" ] && [ -n "$vpn" ] && [ "$wan" != "$vpn" ]; then break; fi
+          [ "$wan" = "$vpn" ] && vpn=""   # not steered yet; re-poll
+          sleep 5
+        done
+        echo "wan=$wan vpn=$vpn"
+        [ -n "$wan" ] || { echo "FAIL: no WAN IP from internet-class pod" >&2; exit 1; }
+        [ -n "$vpn" ] || { echo "FAIL: vpn-class egress not working at baseline" >&2; exit 1; }
+        [ "$wan" != "$vpn" ] || { echo "FAIL: vpn-class == WAN at baseline (not tunneled)" >&2; exit 1; }
+        echo "TUNNEL_HEALTHY_OK"
+    l.go:52: | 01:44:43 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        wan=136.51.115.252 vpn=158.173.241.11
+        TUNNEL_HEALTHY_OK
+    l.go:52: | 01:44:43 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:44:43 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 01:44:43 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:44:43 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mAPPLY[0;22m     | [36;1mRUN[0;22m   | batch/v1/Job @ chainsaw-credible-bird/tunnel-stop
+    l.go:52: | 01:44:43 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | batch/v1/Job @ chainsaw-credible-bird/tunnel-stop
+    l.go:52: | 01:44:43 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mAPPLY[0;22m     | [32;1mDONE[0;22m  | batch/v1/Job @ chainsaw-credible-bird/tunnel-stop
+    l.go:52: | 01:44:43 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mASSERT[0;22m    | [36;1mRUN[0;22m   | batch/v1/Job @ chainsaw-credible-bird/tunnel-stop
+    l.go:52: | 01:44:48 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mASSERT[0;22m    | [32;1mDONE[0;22m  | batch/v1/Job @ chainsaw-credible-bird/tunnel-stop
+    l.go:52: | 01:44:48 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -u
+        ns="$NAMESPACE"
+        wan="$(kubectl -n "$ns" exec egress-internet -c curl -- \
+                 curl -fsS --max-time 10 https://api.ipify.org 2>/dev/null || true)"
+        for i in $(seq 1 8); do
+          out="$(kubectl -n "$ns" exec egress-vpn -c curl -- \
+                   curl -fsS --max-time 8 https://api.ipify.org 2>/dev/null || true)"
+          if [ -n "$out" ]; then
+            if [ -n "$wan" ] && [ "$out" = "$wan" ]; then
+              echo "LEAK: vpn-class reached the WAN IP ($out) with the tunnel DOWN" >&2; exit 1
+            fi
+            echo "LEAK: vpn-class reached the internet ($out) with the tunnel DOWN" >&2; exit 1
+          fi
+          echo "attempt $i: vpn-class blackholed (no response), good"
+          sleep 3
+        done
+        echo "NO_LEAK_OK"
+    l.go:52: | 01:46:18 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        attempt 1: vpn-class blackholed (no response), good
+        attempt 2: vpn-class blackholed (no response), good
+        attempt 3: vpn-class blackholed (no response), good
+        attempt 4: vpn-class blackholed (no response), good
+        attempt 5: vpn-class blackholed (no response), good
+        attempt 6: vpn-class blackholed (no response), good
+        attempt 7: vpn-class blackholed (no response), good
+        attempt 8: vpn-class blackholed (no response), good
+        NO_LEAK_OK
+    l.go:52: | 01:46:18 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:46:18 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        ns="$NAMESPACE"
+        out="$(kubectl -n "$ns" exec egress-internet -c curl -- \
+                 curl -fsS --max-time 10 https://api.ipify.org 2>/dev/null || true)"
+        echo "internet_ip=$out"
+        [ -n "$out" ] || { echo "FAIL: internet-class egress broke while tunnel down (must be unaffected)" >&2; exit 1; }
+        echo "INTERNET_UNAFFECTED_OK"
+    l.go:52: | 01:46:18 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        internet_ip=136.51.115.252
+        INTERNET_UNAFFECTED_OK
+    l.go:52: | 01:46:18 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:46:18 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 01:46:18 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mFINALLY[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:46:18 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        ns="$NAMESPACE"
+        # Distinct Job name (tunnel-restart) so it never collides with the
+        # tunnel-stop Job. Left-aligned manifest so the block scalar yields
+        # valid YAML at column 0 at runtime.
+        cat <<'JOB' | kubectl -n "$ns" apply -f -
+        apiVersion: batch/v1
+        kind: Job
+        metadata:
+          name: tunnel-restart
+          labels: { app: vpn-killswitch-fault }
+        spec:
+          backoffLimit: 3
+          activeDeadlineSeconds: 90
+          ttlSecondsAfterFinished: 600
+          template:
+            metadata:
+              labels: { app: vpn-killswitch-fault }
+            spec:
+              restartPolicy: Never
+              hostPID: true
+              nodeSelector:
+                homelab.keithjackson.dev/egress-gateway: "true"
+              tolerations:
+                - operator: Exists
+              containers:
+                - name: nsenter
+                  image: busybox:1.37.0
+                  securityContext:
+                    privileged: true
+                  command: ["nsenter","-t","1","-m","-u","-i","-n","-p","--","systemctl","start","vpn-egress-tunnel"]
+        JOB
+        # Block teardown until the restart actually completed on the host — a
+        # leaked-down tunnel is unacceptable. `wait` exits non-zero on failure
+        # or timeout, which (set -e) fails the step and surfaces the problem.
+        kubectl -n "$ns" wait --for=condition=complete --timeout=110s job/tunnel-restart
+        echo "TUNNEL_SELF_HEAL_OK"
+    l.go:52: | 01:46:21 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        job.batch/tunnel-restart created
+        job.batch/tunnel-restart condition met
+        TUNNEL_SELF_HEAL_OK
+    l.go:52: | 01:46:21 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:46:21 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mFINALLY[0;22m   | [36;1mEND[0;22m   |
+    l.go:52: | 01:46:21 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:46:21 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        ns="$NAMESPACE"
+        wan="$(kubectl -n "$ns" exec egress-internet -c curl -- \
+                 curl -fsS --max-time 10 https://api.ipify.org 2>/dev/null || true)"
+        vpn=""
+        for i in $(seq 1 24); do
+          vpn="$(kubectl -n "$ns" exec egress-vpn -c curl -- \
+                   curl -fsS --max-time 8 https://api.ipify.org 2>/dev/null || true)"
+          if [ -n "$vpn" ] && [ "$vpn" != "$wan" ]; then break; fi
+          vpn=""
+          sleep 5
+        done
+        echo "recovered_vpn=$vpn wan=$wan"
+        [ -n "$vpn" ] || { echo "FAIL: vpn-class egress did not recover after tunnel restart" >&2; exit 1; }
+        [ "$vpn" != "$wan" ] || { echo "FAIL: vpn-class egress recovered onto the WAN (not tunneled)" >&2; exit 1; }
+        echo "TUNNEL_RECOVERED_OK"
+    l.go:52: | 01:46:25 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        recovered_vpn=158.173.241.11 wan=136.51.115.252
+        TUNNEL_RECOVERED_OK
+    l.go:52: | 01:46:25 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:46:25 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 01:46:25 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCLEANUP[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:46:25 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | batch/v1/Job @ chainsaw-credible-bird/tunnel-stop
+    l.go:52: | 01:46:25 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCLEANUP[0;22m   | [36;1mEND[0;22m   |
+    l.go:52: | 01:46:25 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mCLEANUP[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:46:25 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | v1/Pod @ chainsaw-credible-bird/egress-vpn
+    l.go:52: | 01:46:56 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | v1/Pod @ chainsaw-credible-bird/egress-internet
+    l.go:52: | 01:47:26 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mCLEANUP[0;22m   | [36;1mEND[0;22m   |
+    l.go:52: | 01:47:26 | [36;1mvpn-killswitch[0;22m | [36;1m@chainsaw                                [0;22m | [36;1mCLEANUP[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:47:26 | [32;1mvpn-killswitch[0;22m | [32;1m@chainsaw                                [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | v1/Namespace @ chainsaw-credible-bird
+    l.go:52: | 01:47:33 | [36;1mvpn-killswitch[0;22m | [36;1m@chainsaw                                [0;22m | [36;1mCLEANUP[0;22m   | [36;1mEND[0;22m   |
+--- PASS: chainsaw (0.00s)
+    --- PASS: chainsaw/vpn-killswitch (174.63s)
+PASS
+Tests Summary...
+- Passed  tests 1
+- Failed  tests 0
+- Skipped tests 0
+Done.
+[1m[run.sh][0m HEAVY pass: no heavy tests selected.
+merge_junit: merged 1 report(s) -> /work/.claude/conf-clone/conformance/_artifacts/report.junit.xml (tests=1 failures=0 errors=0 skipped=0)
+[1m[run.sh][0m Done. JUnit: /work/.claude/conf-clone/conformance/_artifacts/report.junit.xml | Coverage: /work/.claude/conf-clone/conformance/_artifacts/coverage/coverage.md
@@ -0,0 +1,4 @@
+<testsuites name="chainsaw-report" tests="1" failures="0" errors="0" time="0.000000"><testsuite name="/work/.claude/conf-clone/conformance/tests/l3-fault-injection/vpn-killswitch" tests="1" failures="0" errors="0" id="0" time="">
+    <testcase name="vpn-killswitch" classname="" time="173.473422" />
+  </testsuite>
+</testsuites>
@@ -0,0 +1,237 @@
+[1m[run.sh][0m Coverage report first (always)
+[coverage] 49/51 requirements have a scaffolded test (96.1%); 2 gap(s), 0 safety-critical gap(s).
+[coverage] wrote /work/.claude/conf-clone/conformance/_artifacts/coverage/coverage.md and /work/.claude/conf-clone/conformance/_artifacts/coverage/coverage.json
+[1m[run.sh][0m No L0/L1 offline checks match the selection (layer=l3 reqs='R-NET-06').
+[1m[run.sh][0m LIGHT pass: 1 test(s), parallel=2 (pinned v0.2.12)
+Version: 0.2.12
+Loading config (/work/.claude/conf-clone/conformance/config/chainsaw-config.yaml)...
+- Using test file: chainsaw-test
+- TestDirs [/work/.claude/conf-clone/conformance/tests/l3-fault-injection/vpn-killswitch]
+- SkipDelete false
+- FailFast false
+- ReportFormat 'JUNIT-TEST'
+- ReportName 'chainsaw-report-light'
+- ReportPath '/work/.claude/conf-clone/conformance/_artifacts'
+- Namespace ''
+- FullName false
+- IncludeTestRegex ''
+- ExcludeTestRegex ''
+- ApplyTimeout 1m30s
+- AssertTimeout 3m0s
+- CleanupTimeout 2m0s
+- DeleteTimeout 2m0s
+- ErrorTimeout 1m0s
+- ExecTimeout 3m0s
+- DeletionPropagationPolicy Background
+- Parallel 2
+- Template true
+- NoCluster false
+- PauseOnFailure false
+Loading tests...
+- vpn-killswitch (/work/.claude/conf-clone/conformance/tests/l3-fault-injection/vpn-killswitch)
+Loading values...
+Running tests...
+=== RUN   chainsaw
+=== PAUSE chainsaw
+=== CONT  chainsaw
+=== RUN   chainsaw/vpn-killswitch
+=== PAUSE chainsaw/vpn-killswitch
+=== CONT  chainsaw/vpn-killswitch
+    l.go:52: | 01:49:24 | [32;1mvpn-killswitch[0;22m | [32;1m@chainsaw                                [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | v1/Namespace @ chainsaw-beloved-toad
+    l.go:52: | 01:49:24 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:49:24 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        kubectl label namespace "$NAMESPACE" \
+          pod-security.kubernetes.io/enforce=privileged \
+          pod-security.kubernetes.io/warn=privileged \
+          pod-security.kubernetes.io/audit=privileged \
+          --overwrite
+        echo "NS_PRIVILEGED_OK"
+    l.go:52: | 01:49:24 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        namespace/chainsaw-beloved-toad labeled
+        NS_PRIVILEGED_OK
+    l.go:52: | 01:49:24 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:49:24 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mAPPLY[0;22m     | [36;1mRUN[0;22m   | v1/Pod @ chainsaw-beloved-toad/egress-internet
+    l.go:52: | 01:49:24 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | v1/Pod @ chainsaw-beloved-toad/egress-internet
+    l.go:52: | 01:49:24 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mAPPLY[0;22m     | [32;1mDONE[0;22m  | v1/Pod @ chainsaw-beloved-toad/egress-internet
+    l.go:52: | 01:49:24 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mAPPLY[0;22m     | [36;1mRUN[0;22m   | v1/Pod @ chainsaw-beloved-toad/egress-vpn
+    l.go:52: | 01:49:25 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | v1/Pod @ chainsaw-beloved-toad/egress-vpn
+    l.go:52: | 01:49:25 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mAPPLY[0;22m     | [32;1mDONE[0;22m  | v1/Pod @ chainsaw-beloved-toad/egress-vpn
+    l.go:52: | 01:49:25 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mASSERT[0;22m    | [36;1mRUN[0;22m   | v1/Pod @ chainsaw-beloved-toad/egress-internet
+    l.go:52: | 01:49:26 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mASSERT[0;22m    | [32;1mDONE[0;22m  | v1/Pod @ chainsaw-beloved-toad/egress-internet
+    l.go:52: | 01:49:26 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mASSERT[0;22m    | [36;1mRUN[0;22m   | v1/Pod @ chainsaw-beloved-toad/egress-vpn
+    l.go:52: | 01:49:26 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mASSERT[0;22m    | [32;1mDONE[0;22m  | v1/Pod @ chainsaw-beloved-toad/egress-vpn
+    l.go:52: | 01:49:26 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        ns="$NAMESPACE"
+        get_ip() {
+          kubectl -n "$ns" exec "$1" -c curl -- \
+            curl -fsS --max-time 10 https://api.ipify.org 2>/dev/null || true
+        }
+        wan="" vpn=""
+        for i in $(seq 1 12); do
+          [ -n "$wan" ] || wan="$(get_ip egress-internet)"
+          [ -n "$vpn" ] || vpn="$(get_ip egress-vpn)"
+          if [ -n "$wan" ] && [ -n "$vpn" ] && [ "$wan" != "$vpn" ]; then break; fi
+          [ "$wan" = "$vpn" ] && vpn=""   # not steered yet; re-poll
+          sleep 5
+        done
+        echo "wan=$wan vpn=$vpn"
+        [ -n "$wan" ] || { echo "FAIL: no WAN IP from internet-class pod" >&2; exit 1; }
+        [ -n "$vpn" ] || { echo "FAIL: vpn-class egress not working at baseline" >&2; exit 1; }
+        [ "$wan" != "$vpn" ] || { echo "FAIL: vpn-class == WAN at baseline (not tunneled)" >&2; exit 1; }
+        echo "TUNNEL_HEALTHY_OK"
+    l.go:52: | 01:49:27 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        wan=136.51.115.252 vpn=158.173.241.11
+        TUNNEL_HEALTHY_OK
+    l.go:52: | 01:49:27 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:49:27 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 01:49:27 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:49:27 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mAPPLY[0;22m     | [36;1mRUN[0;22m   | batch/v1/Job @ chainsaw-beloved-toad/tunnel-stop
+    l.go:52: | 01:49:27 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | batch/v1/Job @ chainsaw-beloved-toad/tunnel-stop
+    l.go:52: | 01:49:27 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mAPPLY[0;22m     | [32;1mDONE[0;22m  | batch/v1/Job @ chainsaw-beloved-toad/tunnel-stop
+    l.go:52: | 01:49:27 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mASSERT[0;22m    | [36;1mRUN[0;22m   | batch/v1/Job @ chainsaw-beloved-toad/tunnel-stop
+    l.go:52: | 01:49:31 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mASSERT[0;22m    | [32;1mDONE[0;22m  | batch/v1/Job @ chainsaw-beloved-toad/tunnel-stop
+    l.go:52: | 01:49:31 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -u
+        ns="$NAMESPACE"
+        wan="$(kubectl -n "$ns" exec egress-internet -c curl -- \
+                 curl -fsS --max-time 10 https://api.ipify.org 2>/dev/null || true)"
+        for i in $(seq 1 8); do
+          out="$(kubectl -n "$ns" exec egress-vpn -c curl -- \
+                   curl -fsS --max-time 8 https://api.ipify.org 2>/dev/null || true)"
+          if [ -n "$out" ]; then
+            if [ -n "$wan" ] && [ "$out" = "$wan" ]; then
+              echo "LEAK: vpn-class reached the WAN IP ($out) with the tunnel DOWN" >&2; exit 1
+            fi
+            echo "LEAK: vpn-class reached the internet ($out) with the tunnel DOWN" >&2; exit 1
+          fi
+          echo "attempt $i: vpn-class blackholed (no response), good"
+          sleep 3
+        done
+        echo "NO_LEAK_OK"
+    l.go:52: | 01:51:01 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        attempt 1: vpn-class blackholed (no response), good
+        attempt 2: vpn-class blackholed (no response), good
+        attempt 3: vpn-class blackholed (no response), good
+        attempt 4: vpn-class blackholed (no response), good
+        attempt 5: vpn-class blackholed (no response), good
+        attempt 6: vpn-class blackholed (no response), good
+        attempt 7: vpn-class blackholed (no response), good
+        attempt 8: vpn-class blackholed (no response), good
+        NO_LEAK_OK
+    l.go:52: | 01:51:01 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:51:01 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        ns="$NAMESPACE"
+        out="$(kubectl -n "$ns" exec egress-internet -c curl -- \
+                 curl -fsS --max-time 10 https://api.ipify.org 2>/dev/null || true)"
+        echo "internet_ip=$out"
+        [ -n "$out" ] || { echo "FAIL: internet-class egress broke while tunnel down (must be unaffected)" >&2; exit 1; }
+        echo "INTERNET_UNAFFECTED_OK"
+    l.go:52: | 01:51:02 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        internet_ip=136.51.115.252
+        INTERNET_UNAFFECTED_OK
+    l.go:52: | 01:51:02 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:51:02 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 01:51:02 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mFINALLY[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:51:02 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        ns="$NAMESPACE"
+        # Distinct Job name (tunnel-restart) so it never collides with the
+        # tunnel-stop Job. Left-aligned manifest so the block scalar yields
+        # valid YAML at column 0 at runtime.
+        cat <<'JOB' | kubectl -n "$ns" apply -f -
+        apiVersion: batch/v1
+        kind: Job
+        metadata:
+          name: tunnel-restart
+          labels: { app: vpn-killswitch-fault }
+        spec:
+          backoffLimit: 3
+          activeDeadlineSeconds: 90
+          ttlSecondsAfterFinished: 600
+          template:
+            metadata:
+              labels: { app: vpn-killswitch-fault }
+            spec:
+              restartPolicy: Never
+              hostPID: true
+              nodeSelector:
+                homelab.keithjackson.dev/egress-gateway: "true"
+              tolerations:
+                - operator: Exists
+              containers:
+                - name: nsenter
+                  image: busybox:1.37.0
+                  securityContext:
+                    privileged: true
+                  command: ["nsenter","-t","1","-m","-u","-i","-n","-p","--","systemctl","start","vpn-egress-tunnel"]
+        JOB
+        # Block teardown until the restart actually completed on the host — a
+        # leaked-down tunnel is unacceptable. `wait` exits non-zero on failure
+        # or timeout, which (set -e) fails the step and surfaces the problem.
+        kubectl -n "$ns" wait --for=condition=complete --timeout=110s job/tunnel-restart
+        echo "TUNNEL_SELF_HEAL_OK"
+    l.go:52: | 01:51:05 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        job.batch/tunnel-restart created
+        job.batch/tunnel-restart condition met
+        TUNNEL_SELF_HEAL_OK
+    l.go:52: | 01:51:05 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:51:05 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mFINALLY[0;22m   | [36;1mEND[0;22m   |
+    l.go:52: | 01:51:05 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:51:05 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        ns="$NAMESPACE"
+        wan="$(kubectl -n "$ns" exec egress-internet -c curl -- \
+                 curl -fsS --max-time 10 https://api.ipify.org 2>/dev/null || true)"
+        vpn=""
+        for i in $(seq 1 24); do
+          vpn="$(kubectl -n "$ns" exec egress-vpn -c curl -- \
+                   curl -fsS --max-time 8 https://api.ipify.org 2>/dev/null || true)"
+          if [ -n "$vpn" ] && [ "$vpn" != "$wan" ]; then break; fi
+          vpn=""
+          sleep 5
+        done
+        echo "recovered_vpn=$vpn wan=$wan"
+        [ -n "$vpn" ] || { echo "FAIL: vpn-class egress did not recover after tunnel restart" >&2; exit 1; }
+        [ "$vpn" != "$wan" ] || { echo "FAIL: vpn-class egress recovered onto the WAN (not tunneled)" >&2; exit 1; }
+        echo "TUNNEL_RECOVERED_OK"
+    l.go:52: | 01:51:08 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        recovered_vpn=158.173.241.11 wan=136.51.115.252
+        TUNNEL_RECOVERED_OK
+    l.go:52: | 01:51:08 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 01:51:08 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-tunnel-recovers-connectivity-returns[0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 01:51:08 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCLEANUP[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:51:08 | [32;1mvpn-killswitch[0;22m | [32;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | batch/v1/Job @ chainsaw-beloved-toad/tunnel-stop
+    l.go:52: | 01:51:08 | [36;1mvpn-killswitch[0;22m | [36;1mwhen-force-tunnel-down-then-no-leak      [0;22m | [36;1mCLEANUP[0;22m   | [36;1mEND[0;22m   |
+    l.go:52: | 01:51:08 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mCLEANUP[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:51:08 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | v1/Pod @ chainsaw-beloved-toad/egress-vpn
+    l.go:52: | 01:51:39 | [32;1mvpn-killswitch[0;22m | [32;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | v1/Pod @ chainsaw-beloved-toad/egress-internet
+    l.go:52: | 01:52:10 | [36;1mvpn-killswitch[0;22m | [36;1mgiven-healthy-tunnel-and-two-workloads   [0;22m | [36;1mCLEANUP[0;22m   | [36;1mEND[0;22m   |
+    l.go:52: | 01:52:10 | [36;1mvpn-killswitch[0;22m | [36;1m@chainsaw                                [0;22m | [36;1mCLEANUP[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 01:52:10 | [32;1mvpn-killswitch[0;22m | [32;1m@chainsaw                                [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | v1/Namespace @ chainsaw-beloved-toad
+    l.go:52: | 01:52:18 | [36;1mvpn-killswitch[0;22m | [36;1m@chainsaw                                [0;22m | [36;1mCLEANUP[0;22m   | [36;1mEND[0;22m   |
+--- PASS: chainsaw (0.00s)
+    --- PASS: chainsaw/vpn-killswitch (173.47s)
+PASS
+Tests Summary...
+- Passed  tests 1
+- Failed  tests 0
+- Skipped tests 0
+Done.
+[1m[run.sh][0m HEAVY pass: no heavy tests selected.
+merge_junit: merged 1 report(s) -> /work/.claude/conf-clone/conformance/_artifacts/report.junit.xml (tests=1 failures=0 errors=0 skipped=0)
+[1m[run.sh][0m Done. JUnit: /work/.claude/conf-clone/conformance/_artifacts/report.junit.xml | Coverage: /work/.claude/conf-clone/conformance/_artifacts/coverage/coverage.md
@@ -0,0 +1,4 @@
+<testsuites name="chainsaw-report" tests="1" failures="0" errors="0" time="0.000000"><testsuite name="/work/conformance/tests/l3-fault-injection/dr-restore" tests="1" failures="0" errors="0" id="0" time="">
+    <testcase name="dr-restore" classname="" time="150.698290" />
+  </testsuite>
+</testsuites>
@@ -0,0 +1,672 @@
+[1m[run.sh][0m Coverage report first (always)
+[coverage] 51/51 requirements have a scaffolded test (100.0%); 0 gap(s), 0 safety-critical gap(s).
+[coverage] wrote /work/conformance/_artifacts/coverage/coverage.md and /work/conformance/_artifacts/coverage/coverage.json
+[1m[run.sh][0m No L0/L1 offline checks match the selection (layer=l3 reqs='R-STATE-03').
+[1m[run.sh][0m LIGHT pass: no tests selected.
+[1m[run.sh][0m HEAVY pass: 1 test(s) SERIAL (parallel=1) — dr-restore
+Version: 0.2.12
+Loading config (/work/conformance/config/chainsaw-config.yaml)...
+- Using test file: chainsaw-test
+- TestDirs [/work/conformance/tests/l3-fault-injection/dr-restore]
+- SkipDelete false
+- FailFast false
+- ReportFormat 'JUNIT-TEST'
+- ReportName 'chainsaw-report-heavy'
+- ReportPath '/work/conformance/_artifacts'
+- Namespace ''
+- FullName false
+- IncludeTestRegex ''
+- ExcludeTestRegex ''
+- ApplyTimeout 1m30s
+- AssertTimeout 3m0s
+- CleanupTimeout 2m0s
+- DeleteTimeout 2m0s
+- ErrorTimeout 1m0s
+- ExecTimeout 3m0s
+- DeletionPropagationPolicy Background
+- Parallel 1
+- Template true
+- NoCluster false
+- PauseOnFailure false
+Loading tests...
+- dr-restore (/work/conformance/tests/l3-fault-injection/dr-restore)
+Loading values...
+Running tests...
+=== RUN   chainsaw
+=== PAUSE chainsaw
+=== CONT  chainsaw
+=== RUN   chainsaw/dr-restore
+=== PAUSE chainsaw/dr-restore
+=== CONT  chainsaw/dr-restore
+    l.go:52: | 02:15:05 | [32;1mdr-restore[0;22m | [32;1m@chainsaw                                [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | v1/Namespace @ chainsaw-glorious-sheep
+    l.go:52: | 02:15:05 | [36;1mdr-restore[0;22m | [36;1massert-backup-target-is-off-cluster      [0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 02:15:05 | [36;1mdr-restore[0;22m | [36;1massert-backup-target-is-off-cluster      [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        
+        # ---- helpers -------------------------------------------------------
+        # Classify a kubectl failure: an RBAC denial is a HARNESS DEFECT and must
+        # fail loudly; an absent API is a genuine precondition gap and may skip.
+        die_or_skip() {
+          case "$2" in
+            *orbidden*|*Unauthorized*|*cannot\ list*|*cannot\ get*)
+              echo "FAIL: conformance runner lacks RBAC for $1 -- fix conformance/incluster/rbac.yaml" >&2
+              echo "$2" >&2
+              exit 1 ;;
+            *)
+              echo "SKIP: $1 not available on this cluster -- $2"
+              echo DR_RESTORE_SKIPPED_OK
+              exit 0 ;;
+          esac
+        }
+        
+        ip2int() {
+          _q="$(echo "$1" | tr '.' ' ')"
+          set -- $_q
+          [ $# -eq 4 ] || { echo -1; return 0; }
+          echo $(( ($1 * 16777216) + ($2 * 65536) + ($3 * 256) + $4 ))
+        }
+        
+        # in_cidr <ip> <a.b.c.d/len> -> 0 when the ip is inside the prefix
+        in_cidr() {
+          case "$2" in *"/"*) ;; *) return 1 ;; esac
+          _net="${2%/*}"; _len="${2#*/}"
+          case "$_len" in ''|*[!0-9]*) return 1 ;; esac
+          [ "$_len" -ge 0 ] && [ "$_len" -le 32 ] || return 1
+          _i="$(ip2int "$1")"; _n="$(ip2int "$_net")"
+          [ "$_i" -ge 0 ] && [ "$_n" -ge 0 ] || return 1
+          [ "$_len" -eq 0 ] && return 0
+          _d=1; _s=0
+          while [ "$_s" -lt $((32 - _len)) ]; do _d=$((_d * 2)); _s=$((_s + 1)); done
+          [ $(( _i / _d )) -eq $(( _n / _d )) ]
+        }
+        
+        # ---- Gate 1: the replicated storage tier the DR-critical data lives on --
+        if ! kubectl get storageclass longhorn >/dev/null 2>&1; then
+          echo "SKIP: 'longhorn' StorageClass absent -- no DR-critical data tier on this cluster yet"
+          echo DR_RESTORE_SKIPPED_OK
+          exit 0
+        fi
+        
+        # ---- Gate 2: the Velero API + a configured BackupStorageLocation --------
+        BSL_LINES="$(kubectl get backupstoragelocations.velero.io -A \
+          -o jsonpath='{range .items[*]}{.metadata.namespace}{" "}{.metadata.name}{" "}{.status.phase}{" "}{.spec.provider}{" "}{.spec.default}{" "}{.spec.config.s3Url}{" "}{.spec.objectStorage.bucket}{"\n"}{end}' \
+          2>&1)" || die_or_skip "velero.io/backupstoragelocations" "$BSL_LINES"
+        if [ -z "$(echo "$BSL_LINES" | tr -d '[:space:]')" ]; then
+          echo "SKIP: Velero API present but NO BackupStorageLocation is configured -- no off-cluster backup target yet"
+          echo DR_RESTORE_SKIPPED_OK
+          exit 0
+        fi
+        echo "backup storage locations:"
+        echo "$BSL_LINES"
+        
+        VNS="$(echo "$BSL_LINES" | head -1 | cut -d' ' -f1)"
+        
+        # ---- Gate 3: Velero server + node-agent (kopia FSB) actually ready -------
+        # File System Backup is the volume-DATA path (platform/velero/helmrelease.yaml:
+        # deployNodeAgent=true, uploaderType=kopia, snapshotsEnabled=false). Without a
+        # ready node-agent no volume data can be captured, so the drill is not runnable.
+        VREADY=0; NAREADY=0
+        for i in $(seq 1 12); do
+          VREADY="$(kubectl -n "$VNS" get deploy velero -o jsonpath='{.status.readyReplicas}' 2>/dev/null || true)"
+          NAREADY="$(kubectl -n "$VNS" get daemonset node-agent -o jsonpath='{.status.numberReady}' 2>/dev/null || true)"
+          echo "poll $i: velero readyReplicas=${VREADY:-0} node-agent numberReady=${NAREADY:-0}"
+          if [ "${VREADY:-0}" -ge 1 ] && [ "${NAREADY:-0}" -ge 1 ]; then break; fi
+          sleep 10
+        done
+        if [ "${VREADY:-0}" -lt 1 ] || [ "${NAREADY:-0}" -lt 1 ]; then
+          echo "SKIP: Velero server and/or its node-agent DaemonSet are not ready in ns '$VNS' -- backup/restore path not available"
+          echo DR_RESTORE_SKIPPED_OK
+          exit 0
+        fi
+        
+        # ---- Pick the BSL this drill will use: prefer the default, and it MUST be
+        #      Available. A CONFIGURED-BUT-UNAVAILABLE target is NOT a precondition
+        #      gap -- it is a live R-STATE-03 defect, so it FAILS (after a bounded
+        #      wait for first-validation on a cold start), it does not skip. --------
+        BSL_NS=""; BSL_NAME=""; BSL_URL=""; BSL_BUCKET=""
+        for i in $(seq 1 12); do
+          BSL_LINES="$(kubectl get backupstoragelocations.velero.io -A \
+            -o jsonpath='{range .items[*]}{.metadata.namespace}{" "}{.metadata.name}{" "}{.status.phase}{" "}{.spec.provider}{" "}{.spec.default}{" "}{.spec.config.s3Url}{" "}{.spec.objectStorage.bucket}{"\n"}{end}' 2>/dev/null || true)"
+          CAND="$(echo "$BSL_LINES" | grep ' Available ' | grep ' true ' | head -1 || true)"
+          [ -n "$CAND" ] || CAND="$(echo "$BSL_LINES" | grep ' Available ' | head -1 || true)"
+          if [ -n "$CAND" ]; then
+            BSL_NS="$(echo "$CAND" | cut -d' ' -f1)"
+            BSL_NAME="$(echo "$CAND" | cut -d' ' -f2)"
+            BSL_URL="$(echo "$CAND" | cut -d' ' -f6)"
+            BSL_BUCKET="$(echo "$CAND" | cut -d' ' -f7)"
+            break
+          fi
+          echo "poll $i: no Available BackupStorageLocation yet"
+          sleep 10
+        done
+        if [ -z "$BSL_NAME" ]; then
+          echo "FAIL: a BackupStorageLocation is configured but NONE reached phase 'Available'." >&2
+          echo "      The off-cluster backup target is unreachable -- R-STATE-03 is BROKEN, not merely untested." >&2
+          echo "$BSL_LINES" >&2
+          exit 1
+        fi
+        echo "using BSL ${BSL_NS}/${BSL_NAME}  bucket=${BSL_BUCKET}  endpoint=${BSL_URL}"
+        
+        # ---- OFF-CLUSTER PROOF (1): an endpoint we can evaluate ------------------
+        if [ -z "$BSL_URL" ]; then
+          echo "FAIL: BackupStorageLocation ${BSL_NS}/${BSL_NAME} exposes no spec.config.s3Url;" >&2
+          echo "      the OFF-CLUSTER property of the backup target cannot be established, so this" >&2
+          echo "      test refuses to claim it. (Extend this check for a non-S3 provider.)" >&2
+          exit 1
+        fi
+        HOST="${BSL_URL#*://}"      # strip scheme
+        HOST="${HOST%%/*}"          # strip path
+        HOST="${HOST%%:*}"          # strip port
+        echo "backup endpoint host: $HOST"
+        
+        case "$HOST" in
+          localhost|*.svc|*.svc.cluster.local|*.cluster.local)
+            echo "FAIL: backup endpoint '$HOST' is a CLUSTER-INTERNAL name -- the backup target is IN the cluster." >&2
+            echo "      An in-cluster backup store cannot satisfy R-STATE-03 (off-cluster backup)." >&2
+            exit 1 ;;
+        esac
+        
+        # Resolve to an IPv4 address. If it cannot be resolved we CANNOT establish the
+        # off-cluster property -- that is a failure, never a silent pass.
+        case "$HOST" in
+          *[!0-9.]*)
+            # Endpoint given as a name. Try the resolvers that may exist in the
+            # runner image, in order; if none is available or none resolves, the
+            # test FAILS below rather than guessing.
+            EPIP="$(getent ahostsv4 "$HOST" 2>/dev/null | head -1 | cut -d' ' -f1 || true)"
+            [ -n "$EPIP" ] || EPIP="$(getent hosts "$HOST" 2>/dev/null | head -1 | cut -d' ' -f1 || true)"
+            [ -n "$EPIP" ] || EPIP="$(nslookup "$HOST" 2>/dev/null | grep -A2 '^Name:' | grep '^Address' | head -1 | sed 's/.*: *//' || true)" ;;
+          *) EPIP="$HOST" ;;
+        esac
+        if [ -z "$EPIP" ]; then
+          echo "FAIL: could not resolve backup endpoint host '$HOST' to an IPv4 address;" >&2
+          echo "      the OFF-CLUSTER property cannot be asserted, so this test does not pass." >&2
+          exit 1
+        fi
+        echo "backup endpoint resolves to: $EPIP"
+        
+        # ---- OFF-CLUSTER PROOF (2): the endpoint is outside every cluster address --
+        case "$EPIP" in 127.*|0.0.0.0) echo "FAIL: backup endpoint $EPIP is loopback -- not off-cluster" >&2; exit 1 ;; esac
+        
+        NODE_IPS="$(kubectl get nodes -o jsonpath='{range .items[*]}{range .status.addresses[*]}{.address}{"\n"}{end}{end}' 2>/dev/null || true)"
+        for a in $NODE_IPS; do
+          if [ "$a" = "$EPIP" ]; then
+            echo "FAIL: backup endpoint $EPIP is a NODE address of this cluster -- the backup is not off-cluster." >&2
+            exit 1
+          fi
+        done
+        echo "endpoint is not any node address (checked $(echo "$NODE_IPS" | grep -c . || true) node addresses)"
+        
+        SVC_IPS="$(kubectl get svc -A -o jsonpath='{range .items[*]}{.spec.clusterIP}{"\n"}{end}' 2>/dev/null || true)"
+        for a in $SVC_IPS; do
+          if [ "$a" = "$EPIP" ]; then
+            echo "FAIL: backup endpoint $EPIP is a Service ClusterIP -- the backup target lives INSIDE the cluster." >&2
+            exit 1
+          fi
+        done
+        echo "endpoint is not any Service ClusterIP (checked $(echo "$SVC_IPS" | grep -c . || true))"
+        
+        POD_IPS="$(kubectl get pods -A -o jsonpath='{range .items[*]}{.status.podIP}{"\n"}{end}' 2>/dev/null || true)"
+        for a in $POD_IPS; do
+          if [ "$a" = "$EPIP" ]; then
+            echo "FAIL: backup endpoint $EPIP is a POD IP -- the backup target is an in-cluster pod." >&2
+            exit 1
+          fi
+        done
+        echo "endpoint is not any Pod IP (checked $(echo "$POD_IPS" | grep -c . || true))"
+        
+        POD_CIDRS="$(kubectl get nodes -o jsonpath='{range .items[*]}{.spec.podCIDR}{"\n"}{range .spec.podCIDRs[*]}{@}{"\n"}{end}{end}' 2>/dev/null || true)"
+        for c in $POD_CIDRS; do
+          case "$c" in *:*) continue ;; esac      # IPv6 prefixes are out of scope here
+          if in_cidr "$EPIP" "$c"; then
+            echo "FAIL: backup endpoint $EPIP falls inside node podCIDR $c -- it is in the cluster pod network." >&2
+            exit 1
+          fi
+        done
+        echo "endpoint is outside every node podCIDR (checked: $(echo "$POD_CIDRS" | tr '\n' ' '))"
+        
+        # Best-effort (needs networking.k8s.io/ServiceCIDR, which the least-privilege
+        # runner may not read): the checks above are the authoritative ones.
+        SVC_CIDRS="$(kubectl get servicecidrs.networking.k8s.io -o jsonpath='{range .items[*]}{range .spec.cidrs[*]}{@}{"\n"}{end}{end}' 2>/dev/null || true)"
+        if [ -n "$SVC_CIDRS" ]; then
+          for c in $SVC_CIDRS; do
+            case "$c" in *:*) continue ;; esac
+            if in_cidr "$EPIP" "$c"; then
+              echo "FAIL: backup endpoint $EPIP falls inside the Service CIDR $c -- it is in the cluster." >&2
+              exit 1
+            fi
+          done
+          echo "endpoint is outside every ServiceCIDR ($(echo "$SVC_CIDRS" | tr '\n' ' '))"
+        else
+          echo "(ServiceCIDR objects unreadable -- skipping that best-effort check; ClusterIP/PodIP/podCIDR checks stand)"
+        fi
+        
+        echo "OFF_CLUSTER_TARGET_OK  bsl=${BSL_NS}/${BSL_NAME} endpoint=${EPIP} bucket=${BSL_BUCKET}"
+    l.go:52: | 02:15:08 | [36;1mdr-restore[0;22m | [36;1massert-backup-target-is-off-cluster      [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        backup storage locations:
+        velero default Available aws true https://7ce452a1b3d6c86daf2c020edcb82d37.r2.cloudflarestorage.com k3s-prod-backup
+        poll 1: velero readyReplicas=1 node-agent numberReady=3
+        using BSL velero/default  bucket=k3s-prod-backup  endpoint=https://7ce452a1b3d6c86daf2c020edcb82d37.r2.cloudflarestorage.com
+        backup endpoint host: 7ce452a1b3d6c86daf2c020edcb82d37.r2.cloudflarestorage.com
+        backup endpoint resolves to: 172.64.66.1
+        endpoint is not any node address (checked 6 node addresses)
+        endpoint is not any Service ClusterIP (checked 82)
+        endpoint is not any Pod IP (checked 197)
+        endpoint is outside every node podCIDR (checked: 10.42.0.0/24 10.42.0.0/24 10.42.1.0/24 10.42.1.0/24 10.42.2.0/24 10.42.2.0/24 )
+        endpoint is outside every ServiceCIDR (10.43.0.0/16 )
+        OFF_CLUSTER_TARGET_OK  bsl=velero/default endpoint=172.64.66.1 bucket=k3s-prod-backup
+    l.go:52: | 02:15:08 | [32;1mdr-restore[0;22m | [32;1massert-backup-target-is-off-cluster      [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 02:15:08 | [36;1mdr-restore[0;22m | [36;1massert-backup-target-is-off-cluster      [0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 02:15:08 | [36;1mdr-restore[0;22m | [36;1massert-backups-are-scheduled             [0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 02:15:08 | [36;1mdr-restore[0;22m | [36;1massert-backups-are-scheduled             [0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        SCHED="$(kubectl get schedules.velero.io -A \
+          -o jsonpath='{range .items[*]}{.metadata.namespace}{"/"}{.metadata.name}{" phase="}{.status.phase}{" cron="}{.spec.schedule}{" lastBackup="}{.status.lastBackup}{"\n"}{end}' 2>/dev/null || true)"
+        if [ -z "$(echo "$SCHED" | tr -d '[:space:]')" ]; then
+          # Distinguish "Velero absent" (skip, in lock-step with step 1) from
+          # "Velero present but nothing scheduled" (a real R-STATE-03 defect).
+          if kubectl get backupstoragelocations.velero.io -A >/dev/null 2>&1; then
+            if [ -z "$(kubectl get backupstoragelocations.velero.io -A -o name 2>/dev/null || true)" ]; then
+              echo "SKIP: no BackupStorageLocation configured -- scheduling not applicable yet"
+              echo DR_SCHEDULE_SKIPPED_OK
+              exit 0
+            fi
+            echo "FAIL: Velero is configured with a backup target but declares NO Schedule --" >&2
+            echo "      R-STATE-03 requires SCHEDULED off-cluster backups, not manual ones." >&2
+            exit 1
+          fi
+          echo "SKIP: Velero API absent -- backup scheduling not applicable on this cluster yet"
+          echo DR_SCHEDULE_SKIPPED_OK
+          exit 0
+        fi
+        echo "velero schedules:"
+        echo "$SCHED"
+        # A Schedule that exists but is paused/disabled backs nothing up.
+        if echo "$SCHED" | grep -q 'phase=Enabled'; then
+          echo BACKUPS_ARE_SCHEDULED_OK
+        else
+          echo "FAIL: no Velero Schedule is in phase 'Enabled' -- scheduled off-cluster backups are not running." >&2
+          exit 1
+        fi
+    l.go:52: | 02:15:08 | [36;1mdr-restore[0;22m | [36;1massert-backups-are-scheduled             [0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        velero schedules:
+        velero/velero-daily phase=Enabled cron=0 3 * * * lastBackup=2026-09-13T04:01:06Z
+        velero/velero-daily-resources-only phase=Enabled cron=0 3 * * * lastBackup=2026-09-13T03:00:03Z
+        BACKUPS_ARE_SCHEDULED_OK
+    l.go:52: | 02:15:08 | [32;1mdr-restore[0;22m | [32;1massert-backups-are-scheduled             [0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 02:15:08 | [36;1mdr-restore[0;22m | [36;1massert-backups-are-scheduled             [0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 02:15:08 | [36;1mdr-restore[0;22m | [36;1mdata-restores-from-the-off-cluster-backup[0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 02:15:08 | [36;1mdr-restore[0;22m | [36;1mdata-restores-from-the-off-cluster-backup[0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -eu
+        NS="$NAMESPACE"
+        SRC="${NS}-dr-src"          # scratch source namespace (destroyed by design)
+        DST="${NS}-dr-dst"          # clean restore target (must not pre-exist)
+        BK="${NS}-dr-backup"
+        RS="${NS}-dr-restore"
+        OWNER_LABEL="conformance.home.k3s/created-by=${NS}"
+        
+        # ---- Re-derive the preconditions (steps do not share shell state). Every
+        #      skip below mirrors step 1 exactly, so the whole test skips or runs
+        #      as a unit -- it can never half-run. -----------------------------
+        if ! kubectl get storageclass longhorn >/dev/null 2>&1; then
+          echo "SKIP: 'longhorn' StorageClass absent"; echo DR_RESTORE_SKIPPED_OK; exit 0
+        fi
+        BSL_LINES="$(kubectl get backupstoragelocations.velero.io -A \
+          -o jsonpath='{range .items[*]}{.metadata.namespace}{" "}{.metadata.name}{" "}{.status.phase}{" "}{.spec.default}{"\n"}{end}' 2>/dev/null || true)"
+        CAND="$(echo "$BSL_LINES" | grep ' Available ' | grep ' true$' | head -1 || true)"
+        [ -n "$CAND" ] || CAND="$(echo "$BSL_LINES" | grep ' Available ' | head -1 || true)"
+        if [ -z "$CAND" ]; then
+          echo "SKIP: no Available BackupStorageLocation (see the off-cluster step for the authoritative verdict)"
+          echo DR_RESTORE_SKIPPED_OK; exit 0
+        fi
+        VNS="$(echo "$CAND" | cut -d' ' -f1)"
+        BSL_NAME="$(echo "$CAND" | cut -d' ' -f2)"
+        if [ "$(kubectl -n "$VNS" get daemonset node-agent -o jsonpath='{.status.numberReady}' 2>/dev/null || echo 0)" -lt 1 ]; then
+          echo "SKIP: Velero node-agent (kopia FSB) not ready -- volume data cannot be backed up"
+          echo DR_RESTORE_SKIPPED_OK; exit 0
+        fi
+        echo "velero ns=$VNS bsl=$BSL_NAME src=$SRC dst=$DST"
+        
+        # A clean restore target means PREVIOUSLY NONEXISTENT, and the source name must
+        # be free. If either is lying around from an aborted run, remove it before we
+        # claim "clean" -- and fail loudly if it will not go, because a half-deleted
+        # namespace would silently invalidate the destroy proof below.
+        kubectl delete namespace "$DST" "$SRC" --ignore-not-found --wait=true --timeout=300s
+        
+        # ============================ GIVEN ==============================
+        # A DR-critical stateful workload with known data on the replicated tier.
+        CANARY="dr-canary-$(date +%s%N)"
+        kubectl create namespace "$SRC"
+        kubectl label namespace "$SRC" "$OWNER_LABEL" --overwrite
+        
+        kubectl -n "$SRC" apply -f - <<EOF
+        apiVersion: v1
+        kind: PersistentVolumeClaim
+        metadata:
+          name: dr-data
+          labels:
+            conformance.home.k3s/created-by: ${NS}
+        spec:
+          accessModes: [ReadWriteOnce]
+          storageClassName: longhorn
+          resources:
+            requests:
+              storage: 1Gi
+        EOF
+        
+        kubectl -n "$SRC" apply -f - <<EOF
+        apiVersion: v1
+        kind: Pod
+        metadata:
+          name: dr-workload
+          labels:
+            app: dr-workload
+            conformance.home.k3s/created-by: ${NS}
+        spec:
+          restartPolicy: Never
+          containers:
+            - name: app
+              image: busybox:1.36.1
+              command: ["sh", "-c", "sleep 7200"]
+              volumeMounts:
+                - name: data
+                  mountPath: /data
+          volumes:
+            - name: data
+              persistentVolumeClaim:
+                claimName: dr-data
+        EOF
+        
+        kubectl -n "$SRC" wait --for=condition=Ready pod/dr-workload --timeout=300s
+        printf '%s' "$CANARY" | kubectl -n "$SRC" exec -i dr-workload -- sh -c 'cat > /data/canary && sync'
+        echo "seeded canary: $(kubectl -n "$SRC" exec dr-workload -- cat /data/canary)"
+        
+        ORIG_PV="$(kubectl -n "$SRC" get pvc dr-data -o jsonpath='{.spec.volumeName}')"
+        [ -n "$ORIG_PV" ] || { echo "FAIL: source PVC never bound to a PV" >&2; exit 1; }
+        echo "original in-cluster PersistentVolume: $ORIG_PV"
+        
+        # ======================= WHEN (part 1): back up off-cluster =======
+        # Created as a Velero Backup CR -- exactly what `velero backup create` does.
+        # defaultVolumesToFsBackup:true selects the kopia File System Backup path, so
+        # the VOLUME DATA (not just the resource JSON) is uploaded to the object store.
+        # ttl is short: if the finally-step DeleteBackupRequest is ever lost, Velero's
+        # own GC still removes this drill's objects from the bucket.
+        kubectl apply -f - <<EOF
+        apiVersion: velero.io/v1
+        kind: Backup
+        metadata:
+          name: ${BK}
+          namespace: ${VNS}
+          labels:
+            conformance.home.k3s/created-by: ${NS}
+        spec:
+          includedNamespaces: [${SRC}]
+          storageLocation: ${BSL_NAME}
+          snapshotVolumes: false
+          defaultVolumesToFsBackup: true
+          ttl: 2h0m0s
+        EOF
+        
+        BPHASE=""
+        for i in $(seq 1 90); do
+          BPHASE="$(kubectl -n "$VNS" get backups.velero.io "$BK" -o jsonpath='{.status.phase}' 2>/dev/null || true)"
+          echo "poll $i: backup phase=${BPHASE:-<pending>}"
+          case "${BPHASE:-}" in
+            Completed|Failed|PartiallyFailed|FailedValidation) break ;;
+          esac
+          sleep 10
+        done
+        if [ "${BPHASE:-}" != "Completed" ]; then
+          echo "FAIL: off-cluster backup did not complete (phase=${BPHASE:-<timeout>})" >&2
+          kubectl -n "$VNS" get backups.velero.io "$BK" -o yaml >&2 || true
+          exit 1
+        fi
+        echo "backup $BK Completed to ${BSL_NAME}"
+        
+        # ---- OFF-CLUSTER PROOF (3): the VOLUME DATA really landed in the remote
+        #      kopia repository -- a PodVolumeBackup Completed with a snapshot ID.
+        PVB="$(kubectl -n "$VNS" get podvolumebackups.velero.io \
+                 -l velero.io/backup-name="$BK" \
+                 -o jsonpath='{range .items[*]}{.metadata.name}{" "}{.status.phase}{" "}{.status.snapshotID}{"\n"}{end}' 2>/dev/null || true)"
+        echo "pod volume backups:"
+        echo "$PVB"
+        if [ -z "$(echo "$PVB" | tr -d '[:space:]')" ]; then
+          echo "FAIL: the backup captured NO pod volume data (no PodVolumeBackup)." >&2
+          echo "      Resource-only backups cannot restore DR-critical DATA." >&2
+          exit 1
+        fi
+        # A line is "<name> <phase> <snapshotID>"; require Completed AND a
+        # non-empty snapshot ID (an empty ID means nothing reached the repository).
+        GOOD_PVB="$(echo "$PVB" | grep -cE ' Completed [^[:space:]]+$' || true)"
+        if [ "${GOOD_PVB:-0}" -lt 1 ]; then
+          echo "FAIL: no PodVolumeBackup reached phase Completed with a snapshot ID --" >&2
+          echo "      the volume data did not reach the off-cluster repository." >&2
+          exit 1
+        fi
+        echo "volume data uploaded off-cluster (PodVolumeBackup Completed with a kopia snapshotID)"
+        
+        # ============ WHEN (part 2): FAULT INJECTION -- annihilate the source ====
+        # Destroy EVERY in-cluster copy: the pod, the PVC, the namespace, and the
+        # underlying PersistentVolume (and with it the Longhorn replicas). After this
+        # there is no in-cluster source the restore could quietly read from.
+        kubectl delete namespace "$SRC" --wait=true --timeout=420s
+        for i in $(seq 1 30); do
+          if ! kubectl get namespace "$SRC" >/dev/null 2>&1; then break; fi
+          echo "poll $i: waiting for namespace $SRC to disappear"
+          sleep 10
+        done
+        if kubectl get namespace "$SRC" >/dev/null 2>&1; then
+          echo "FAIL: source namespace $SRC did not terminate; the destroy step is not convincing" >&2
+          exit 1
+        fi
+        echo "source namespace destroyed"
+        
+        # The longhorn StorageClass reclaims Delete, so the PV should already be gone;
+        # force it if a Retain policy (or a stuck finalizer) left it behind, because a
+        # surviving PV would make the restore prove nothing about off-cluster recovery.
+        kubectl delete pv "$ORIG_PV" --ignore-not-found --wait=false || true
+        for i in $(seq 1 30); do
+          if ! kubectl get pv "$ORIG_PV" >/dev/null 2>&1; then break; fi
+          echo "poll $i: waiting for PersistentVolume $ORIG_PV to disappear"
+          sleep 10
+        done
+        if kubectl get pv "$ORIG_PV" >/dev/null 2>&1; then
+          echo "FAIL: the original PersistentVolume $ORIG_PV SURVIVED the destroy step." >&2
+          echo "      An in-cluster copy of the data still exists, so a successful restore" >&2
+          echo "      would NOT prove recovery from the off-cluster backup. Refusing to pass." >&2
+          exit 1
+        fi
+        echo "original PersistentVolume $ORIG_PV is GONE -- no in-cluster copy of the data remains"
+        
+        # Best-effort corroboration (the least-privilege runner may not read longhorn.io):
+        # the Longhorn Volume CR and its replicas should be gone too.
+        if kubectl -n longhorn-system get volumes.longhorn.io "$ORIG_PV" >/dev/null 2>&1; then
+          echo "FAIL: Longhorn Volume $ORIG_PV still exists after PV deletion -- replicas survive in-cluster" >&2
+          exit 1
+        fi
+        echo "(longhorn Volume CR $ORIG_PV not present -- either deleted or not readable by this identity)"
+        
+        # ============================ RESTORE ============================
+        # Into a CLEAN, previously-nonexistent namespace (Velero creates it), which is
+        # the catalog's "restored into a clean state".
+        kubectl apply -f - <<EOF
+        apiVersion: velero.io/v1
+        kind: Restore
+        metadata:
+          name: ${RS}
+          namespace: ${VNS}
+          labels:
+            conformance.home.k3s/created-by: ${NS}
+        spec:
+          backupName: ${BK}
+          includedNamespaces: [${SRC}]
+          namespaceMapping:
+            ${SRC}: ${DST}
+          existingResourcePolicy: none
+        EOF
+        
+        RPHASE=""
+        for i in $(seq 1 90); do
+          RPHASE="$(kubectl -n "$VNS" get restores.velero.io "$RS" -o jsonpath='{.status.phase}' 2>/dev/null || true)"
+          echo "poll $i: restore phase=${RPHASE:-<pending>}"
+          case "${RPHASE:-}" in
+            Completed|Failed|PartiallyFailed|FailedValidation) break ;;
+          esac
+          sleep 10
+        done
+        if [ "${RPHASE:-}" != "Completed" ]; then
+          echo "FAIL: restore did not complete (phase=${RPHASE:-<timeout>})" >&2
+          kubectl -n "$VNS" get restores.velero.io "$RS" -o yaml >&2 || true
+          kubectl -n "$VNS" get podvolumerestores.velero.io -l velero.io/restore-name="$RS" -o wide >&2 || true
+          exit 1
+        fi
+        echo "restore $RS Completed into $DST"
+        
+        # ============================= THEN ==============================
+        # The service returns WITH ITS DATA. With kopia FSB the restored pod carries a
+        # `restore-wait` init container that blocks until the node-agent has written the
+        # volume contents back, so Ready here already implies the data landed.
+        if ! kubectl -n "$DST" wait --for=condition=Ready pod/dr-workload --timeout=600s; then
+          echo "FAIL: restored workload never became Ready in the clean namespace $DST" >&2
+          kubectl -n "$DST" describe pod dr-workload >&2 || true
+          kubectl -n "$VNS" get podvolumerestores.velero.io -l velero.io/restore-name="$RS" -o wide >&2 || true
+          exit 1
+        fi
+        
+        NEW_PV="$(kubectl -n "$DST" get pvc dr-data -o jsonpath='{.spec.volumeName}' 2>/dev/null || true)"
+        echo "restored PVC bound to PersistentVolume: ${NEW_PV:-<none>}"
+        [ -n "$NEW_PV" ] || { echo "FAIL: restored PVC did not bind a PV" >&2; exit 1; }
+        if [ "$NEW_PV" = "$ORIG_PV" ]; then
+          echo "FAIL: the restored PVC rebound the ORIGINAL PersistentVolume ($ORIG_PV)." >&2
+          echo "      That is an in-cluster survival, not an off-cluster restore." >&2
+          exit 1
+        fi
+        echo "restored onto a NEW volume ($NEW_PV != $ORIG_PV) -- the data came from outside the cluster"
+        
+        GOT="$(kubectl -n "$DST" exec dr-workload -- cat /data/canary)"
+        echo "recovered='$GOT' expected='$CANARY'"
+        if [ "$GOT" != "$CANARY" ]; then
+          echo "FAIL: restored data does not match what was backed up -- DR restore lost/corrupted data" >&2
+          exit 1
+        fi
+        
+        echo DR_RESTORED_FROM_OFF_CLUSTER_BACKUP_OK
+    l.go:52: | 02:17:18 | [36;1mdr-restore[0;22m | [36;1mdata-restores-from-the-off-cluster-backup[0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        velero ns=velero bsl=default src=chainsaw-glorious-sheep-dr-src dst=chainsaw-glorious-sheep-dr-dst
+        namespace/chainsaw-glorious-sheep-dr-src created
+        namespace/chainsaw-glorious-sheep-dr-src labeled
+        persistentvolumeclaim/dr-data created
+        pod/dr-workload created
+        pod/dr-workload condition met
+        seeded canary: dr-canary-1789352108935754215
+        original in-cluster PersistentVolume: pvc-4107d59d-a34f-4cba-bd2a-c5b2446156d9
+        backup.velero.io/chainsaw-glorious-sheep-dr-backup created
+        poll 1: backup phase=InProgress
+        poll 2: backup phase=InProgress
+        poll 3: backup phase=InProgress
+        poll 4: backup phase=Completed
+        backup chainsaw-glorious-sheep-dr-backup Completed to default
+        pod volume backups:
+        chainsaw-glorious-sheep-dr-backup-2gjrq Completed 979eed437233b45c7f85ba80074ab56b
+        volume data uploaded off-cluster (PodVolumeBackup Completed with a kopia snapshotID)
+        namespace "chainsaw-glorious-sheep-dr-src" deleted
+        source namespace destroyed
+        original PersistentVolume pvc-4107d59d-a34f-4cba-bd2a-c5b2446156d9 is GONE -- no in-cluster copy of the data remains
+        (longhorn Volume CR pvc-4107d59d-a34f-4cba-bd2a-c5b2446156d9 not present -- either deleted or not readable by this identity)
+        restore.velero.io/chainsaw-glorious-sheep-dr-restore created
+        poll 1: restore phase=InProgress
+        poll 2: restore phase=InProgress
+        poll 3: restore phase=InProgress
+        poll 4: restore phase=Completed
+        restore chainsaw-glorious-sheep-dr-restore Completed into chainsaw-glorious-sheep-dr-dst
+        pod/dr-workload condition met
+        restored PVC bound to PersistentVolume: pvc-f0c061e1-c080-49f2-a381-23da5c886df2
+        restored onto a NEW volume (pvc-f0c061e1-c080-49f2-a381-23da5c886df2 != pvc-4107d59d-a34f-4cba-bd2a-c5b2446156d9) -- the data came from outside the cluster
+        recovered='dr-canary-1789352108935754215' expected='dr-canary-1789352108935754215'
+        DR_RESTORED_FROM_OFF_CLUSTER_BACKUP_OK
+        === STDERR
+        Defaulted container "app" out of: app, restore-wait (init)
+    l.go:52: | 02:17:18 | [32;1mdr-restore[0;22m | [32;1mdata-restores-from-the-off-cluster-backup[0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 02:17:18 | [36;1mdr-restore[0;22m | [36;1mdata-restores-from-the-off-cluster-backup[0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 02:17:18 | [36;1mdr-restore[0;22m | [36;1mdata-restores-from-the-off-cluster-backup[0;22m | [36;1mFINALLY[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 02:17:18 | [36;1mdr-restore[0;22m | [36;1mdata-restores-from-the-off-cluster-backup[0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -u
+        NS="$NAMESPACE"
+        SRC="${NS}-dr-src"; DST="${NS}-dr-dst"; BK="${NS}-dr-backup"; RS="${NS}-dr-restore"
+        
+        VNS="$(kubectl get backupstoragelocations.velero.io -A -o jsonpath='{.items[0].metadata.namespace}' 2>/dev/null || true)"
+        
+        # Velero objects first: a DeleteBackupRequest makes Velero remove the backup
+        # DATA from the off-cluster bucket, not just the CR (self-cleaning contract).
+        if [ -n "$VNS" ]; then
+          kubectl -n "$VNS" delete restores.velero.io "$RS" --ignore-not-found --wait=false || true
+          if kubectl -n "$VNS" get backups.velero.io "$BK" >/dev/null 2>&1; then
+            kubectl apply -f - <<EOF || true
+        apiVersion: velero.io/v1
+        kind: DeleteBackupRequest
+        metadata:
+          name: ${BK}-delete
+          namespace: ${VNS}
+          labels:
+            conformance.home.k3s/created-by: ${NS}
+        spec:
+          backupName: ${BK}
+        EOF
+            for i in $(seq 1 18); do
+              kubectl -n "$VNS" get backups.velero.io "$BK" >/dev/null 2>&1 || break
+              sleep 10
+            done
+            # Backstop if Velero could not process the request (the 2h ttl also GCs it).
+            kubectl -n "$VNS" delete backups.velero.io "$BK" --ignore-not-found --wait=false || true
+            kubectl -n "$VNS" delete deletebackuprequests.velero.io "${BK}-delete" --ignore-not-found --wait=false || true
+          fi
+          echo "velero objects for $NS cleaned up (ns $VNS)"
+        fi
+        
+        # Scratch namespaces (both, in case the run aborted at any point).
+        for n in "$DST" "$SRC"; do
+          kubectl delete namespace "$n" --ignore-not-found --wait=false || true
+        done
+        # Anything left labelled as ours (defensive; the two names above are the only
+        # namespaces this test ever creates).
+        kubectl delete namespace -l "conformance.home.k3s/created-by=${NS}" --ignore-not-found --wait=false || true
+        
+        # Released PVs from either namespace's PVCs would otherwise leak storage.
+        for pv in $(kubectl get pv -o jsonpath='{range .items[*]}{.metadata.name}{" "}{.spec.claimRef.namespace}{"\n"}{end}' 2>/dev/null | grep -E " (${SRC}|${DST})$" | cut -d' ' -f1 || true); do
+          kubectl delete pv "$pv" --ignore-not-found --wait=false || true
+          echo "released leftover PersistentVolume: $pv"
+        done
+        
+        echo "dr-restore teardown complete (best-effort; every object was created by this test)"
+    l.go:52: | 02:17:30 | [36;1mdr-restore[0;22m | [36;1mdata-restores-from-the-off-cluster-backup[0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        restore.velero.io "chainsaw-glorious-sheep-dr-restore" deleted from velero namespace
+        deletebackuprequest.velero.io/chainsaw-glorious-sheep-dr-backup-delete created
+        velero objects for chainsaw-glorious-sheep cleaned up (ns velero)
+        namespace "chainsaw-glorious-sheep-dr-dst" deleted
+        namespace "chainsaw-glorious-sheep-dr-dst" deleted
+        persistentvolume "pvc-f0c061e1-c080-49f2-a381-23da5c886df2" deleted
+        released leftover PersistentVolume: pvc-f0c061e1-c080-49f2-a381-23da5c886df2
+        dr-restore teardown complete (best-effort; every object was created by this test)
+    l.go:52: | 02:17:30 | [32;1mdr-restore[0;22m | [32;1mdata-restores-from-the-off-cluster-backup[0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 02:17:30 | [36;1mdr-restore[0;22m | [36;1mdata-restores-from-the-off-cluster-backup[0;22m | [36;1mFINALLY[0;22m   | [36;1mEND[0;22m   |
+    l.go:52: | 02:17:30 | [36;1mdr-restore[0;22m | [36;1m@chainsaw                                [0;22m | [36;1mCLEANUP[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 02:17:30 | [32;1mdr-restore[0;22m | [32;1m@chainsaw                                [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | v1/Namespace @ chainsaw-glorious-sheep
+    l.go:52: | 02:17:36 | [36;1mdr-restore[0;22m | [36;1m@chainsaw                                [0;22m | [36;1mCLEANUP[0;22m   | [36;1mEND[0;22m   |
+--- PASS: chainsaw (0.00s)
+    --- PASS: chainsaw/dr-restore (150.70s)
+PASS
+Tests Summary...
+- Passed  tests 1
+- Failed  tests 0
+- Skipped tests 0
+Done.
+merge_junit: merged 1 report(s) -> /work/conformance/_artifacts/report.junit.xml (tests=1 failures=0 errors=0 skipped=0)
+[1m[run.sh][0m Done. JUnit: /work/conformance/_artifacts/report.junit.xml | Coverage: /work/conformance/_artifacts/coverage/coverage.md
@@ -0,0 +1,13 @@
+<?xml version="1.0" ?>
+<testsuites name="home-k3s-conformance" tests="1" failures="0" errors="0" skipped="0">
+  <testsuite name="home-k3s-conformance L0/L1 (offline)" tests="1" failures="0" errors="0" skipped="0">
+    <testcase classname="L0:R-ENV-02,R-STATE-03" name="placeholder-guard-coupling">
+      <properties>
+        <property name="requirements" value="R-ENV-02,R-STATE-03"/>
+        <property name="layer" value="L0"/>
+        <property name="path" value="/work/conformance/tests/l0-static/placeholder-guard-coupling"/>
+        <property name="scope" value=""/>
+      </properties>
+    </testcase>
+  </testsuite>
+</testsuites>
@@ -0,0 +1,7 @@
+[1m[run.sh][0m Coverage report first (always)
+[coverage] 51/51 requirements have a scaffolded test (100.0%); 0 gap(s), 0 safety-critical gap(s).
+[coverage] wrote /work/conformance/_artifacts/coverage/coverage.md and /work/conformance/_artifacts/coverage/coverage.json
+[1m[run.sh][0m Running 1 offline L0/L1 check(s) (no cluster; docs/14).
+[offline] L0  PASS placeholder-guard-coupling (R-ENV-02,R-STATE-03)
+[offline] wrote JUnit (1 case(s), 0 failure(s), 0 skip(s), 0 unwired) -> /work/conformance/_artifacts/report.junit.xml
+[1m[run.sh][0m Done (offline l0). JUnit: /work/conformance/_artifacts/report.junit.xml | Coverage: /work/conformance/_artifacts/coverage/coverage.md
@@ -0,0 +1,6 @@
+[1m[run.sh][0m Coverage report first (always)
+[coverage] 51/51 requirements have a scaffolded test (100.0%); 0 gap(s), 0 safety-critical gap(s).
+[coverage] wrote /home/keith/source/home-network-k3s-impl/conformance/_artifacts/coverage/coverage.md and /home/keith/source/home-network-k3s-impl/conformance/_artifacts/coverage/coverage.json
+[1m[run.sh][0m No L0/L1 offline checks match the selection (layer=l3 reqs='R-STATE-02').
+ERROR: cluster reachable but 'chainsaw' (v0.2.12) not on PATH.
+Install the pinned binary or run via the in-cluster Job (incluster/).
@@ -0,0 +1,4 @@
+<testsuites name="chainsaw-report" tests="1" failures="0" errors="0" time="0.000000"><testsuite name="/work/conformance/tests/l3-fault-injection/node-loss" tests="1" failures="0" errors="0" id="0" time="">
+    <testcase name="node-loss" classname="" time="115.855688" />
+  </testsuite>
+</testsuites>
@@ -0,0 +1,232 @@
+[1m[run.sh][0m Coverage report first (always)
+[coverage] 51/51 requirements have a scaffolded test (100.0%); 0 gap(s), 0 safety-critical gap(s).
+[coverage] wrote /work/conformance/_artifacts/coverage/coverage.md and /work/conformance/_artifacts/coverage/coverage.json
+[1m[run.sh][0m No L0/L1 offline checks match the selection (layer=l3 reqs='R-STATE-02').
+[1m[run.sh][0m LIGHT pass: no tests selected.
+[1m[run.sh][0m HEAVY pass: 1 test(s) SERIAL (parallel=1) — node-loss
+Version: 0.2.12
+Loading config (/work/conformance/config/chainsaw-config.yaml)...
+- Using test file: chainsaw-test
+- TestDirs [/work/conformance/tests/l3-fault-injection/node-loss]
+- SkipDelete false
+- FailFast false
+- ReportFormat 'JUNIT-TEST'
+- ReportName 'chainsaw-report-heavy'
+- ReportPath '/work/conformance/_artifacts'
+- Namespace ''
+- FullName false
+- IncludeTestRegex ''
+- ExcludeTestRegex ''
+- ApplyTimeout 1m30s
+- AssertTimeout 3m0s
+- CleanupTimeout 2m0s
+- DeleteTimeout 2m0s
+- ErrorTimeout 1m0s
+- ExecTimeout 3m0s
+- DeletionPropagationPolicy Background
+- Parallel 1
+- Template true
+- NoCluster false
+- PauseOnFailure false
+Loading tests...
+- node-loss (/work/conformance/tests/l3-fault-injection/node-loss)
+Loading values...
+Running tests...
+=== RUN   chainsaw
+=== PAUSE chainsaw
+=== CONT  chainsaw
+=== RUN   chainsaw/node-loss
+=== PAUSE chainsaw/node-loss
+=== CONT  chainsaw/node-loss
+    l.go:52: | 05:22:26 | [32;1mnode-loss[0;22m | [32;1m@chainsaw                              [0;22m | [32;1mCREATE[0;22m    | [32;1mOK[0;22m    | v1/Namespace @ chainsaw-advanced-boxer
+    l.go:52: | 05:22:26 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mTRY[0;22m       | [36;1mBEGIN[0;22m |
+    l.go:52: | 05:22:26 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -euo pipefail
+        NS="$NAMESPACE"
+        
+        # -- Gate 1: skip cleanly (green) if the longhorn tier is not present yet. --
+        if ! kubectl get storageclass longhorn >/dev/null 2>&1; then
+          echo "SKIP: 'longhorn' StorageClass absent — node-loss not applicable on this cluster yet"
+          echo NODE_LOSS_SKIPPED_OK
+          exit 0
+        fi
+        
+        # -- Gate 2: a 3-replica volume + single-node-loss headroom needs >= 3 Ready nodes. --
+        READY="$(kubectl get nodes \
+          -o jsonpath='{range .items[*]}{.status.conditions[?(@.type=="Ready")].status}{"\n"}{end}' \
+          | grep -c '^True$' || true)"
+        echo "ready nodes: ${READY}"
+        if [ "${READY:-0}" -lt 3 ]; then
+          echo "SKIP: only ${READY:-0} Ready node(s) (<3) — node-loss resilience not meaningful yet"
+          echo NODE_LOSS_SKIPPED_OK
+          exit 0
+        fi
+        
+        CANARY="node-loss-canary-$(date +%s%N)"
+        
+        # -- GIVEN: a Longhorn PVC (platform default SC = 3 replicas across nodes) + a
+        #    writer pod that writes the canary and flushes it to the replicated volume. --
+        kubectl -n "$NS" apply -f - <<EOF
+        apiVersion: v1
+        kind: PersistentVolumeClaim
+        metadata:
+          name: survivor
+        spec:
+          accessModes: [ReadWriteOnce]
+          storageClassName: longhorn
+          resources:
+            requests:
+              storage: 1Gi
+        EOF
+        
+        apply_pod() {
+          kubectl -n "$NS" apply -f - <<EOF
+        apiVersion: v1
+        kind: Pod
+        metadata:
+          name: $1
+        spec:
+          restartPolicy: Never
+          containers:
+            - name: app
+              image: busybox:1.36.1
+              command: ["sh", "-c", "sleep 3600"]
+              volumeMounts:
+                - name: data
+                  mountPath: /data
+          volumes:
+            - name: data
+              persistentVolumeClaim:
+                claimName: survivor
+        EOF
+        }
+        
+        apply_pod writer
+        kubectl -n "$NS" wait --for=condition=Ready pod/writer --timeout=240s
+        printf '%s' "$CANARY" | kubectl -n "$NS" exec -i writer -- sh -c 'cat > /data/canary && sync'
+        echo "wrote canary: $(kubectl -n "$NS" exec writer -- cat /data/canary)"
+        
+        # The victim node is the one the attached volume currently lives on.
+        VICTIM="$(kubectl -n "$NS" get pod writer -o jsonpath='{.spec.nodeName}')"
+        [ -n "$VICTIM" ] || { echo "FAIL: could not determine writer's node" >&2; exit 1; }
+        echo "victim node (currently hosts the attached volume): $VICTIM"
+        
+        # Best-effort precondition log: if the Longhorn Volume CR is readable, show the
+        # volume is genuinely 3-replica/healthy before we take a node. Non-fatal (the
+        # runner is least-privilege and may not have longhorn.io read rights) — the
+        # data-availability assertion below is the authoritative proof, not this.
+        PVNAME="$(kubectl -n "$NS" get pvc survivor -o jsonpath='{.spec.volumeName}' 2>/dev/null || true)"
+        if [ -n "$PVNAME" ]; then
+          kubectl -n longhorn-system get volumes.longhorn.io "$PVNAME" \
+            -o jsonpath='pre-fault robustness={.status.robustness} replicas={.spec.numberOfReplicas}{"\n"}' \
+            2>/dev/null || echo "(Longhorn Volume CR not readable — continuing; data read is the proof)"
+        fi
+        
+        # -- WHEN: FAULT INJECTION — remove the victim node FROM SERVICE. --
+        #    Label it with THIS test's unique namespace so `finally` can always find and
+        #    uncordon exactly this node; then cordon it; then evict ONLY our own writer
+        #    pod, forcing the volume to detach from the victim. (No `drain` — unrelated
+        #    pods on the node are never touched.)
+        kubectl label node "$VICTIM" "conformance.home.k3s/cordoned-by=$NS" --overwrite
+        kubectl cordon "$VICTIM"
+        echo "cordoned + labelled victim node: $VICTIM"
+        kubectl -n "$NS" delete pod writer --wait=true --timeout=240s
+        echo "evicted writer off the victim node; volume detached from $VICTIM"
+        
+        # -- THEN: a fresh workload re-binds the SAME volume. The victim is unschedulable,
+        #    so the scheduler MUST place the reader on a SURVIVING node; Longhorn re-attaches
+        #    the volume there from its replicas on the other nodes. --
+        apply_pod reader
+        kubectl -n "$NS" wait --for=condition=Ready pod/reader --timeout=360s
+        READER_NODE="$(kubectl -n "$NS" get pod reader -o jsonpath='{.spec.nodeName}')"
+        echo "reader scheduled on surviving node: $READER_NODE (victim was $VICTIM)"
+        if [ "$READER_NODE" = "$VICTIM" ]; then
+          echo "FAIL: reader landed back on the cordoned victim node — node was not removed from service" >&2
+          exit 1
+        fi
+        
+        GOT="$(kubectl -n "$NS" exec reader -- cat /data/canary)"
+        echo "recovered='$GOT' expected='$CANARY'"
+        [ "$GOT" = "$CANARY" ] || { echo "FAIL: data not available after node loss" >&2; exit 1; }
+        echo "volume available + data intact from a surviving node"
+        
+        # Best-effort reconvergence log: if the Longhorn Volume CR is readable, wait
+        # (bounded) for robustness to settle back to available (healthy|degraded — both
+        # serve I/O; a healthy 3-replica volume rebuilds a replica once headroom exists).
+        # Non-fatal for the same least-privilege reason as the pre-fault log.
+        if [ -n "$PVNAME" ]; then
+          for i in $(seq 1 30); do
+            ROB="$(kubectl -n longhorn-system get volumes.longhorn.io "$PVNAME" \
+                  -o jsonpath='{.status.robustness}' 2>/dev/null || true)"
+            [ -z "$ROB" ] && { echo "(Longhorn Volume CR not readable — skipping reconvergence log)"; break; }
+            echo "post-fault robustness[$i]=$ROB"
+            case "$ROB" in healthy|degraded) break ;; esac
+            sleep 10
+          done
+        fi
+        
+        echo NODE_LOSS_VOLUME_AVAILABLE_OK
+    l.go:52: | 05:23:37 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        ready nodes: 3
+        persistentvolumeclaim/survivor created
+        pod/writer created
+        pod/writer condition met
+        wrote canary: node-loss-canary-1789795346371286043
+        victim node (currently hosts the attached volume): k3s-prod-2
+        pre-fault robustness=healthy replicas=3
+        node/k3s-prod-2 labeled
+        node/k3s-prod-2 cordoned
+        cordoned + labelled victim node: k3s-prod-2
+        pod "writer" deleted from chainsaw-advanced-boxer namespace
+        evicted writer off the victim node; volume detached from k3s-prod-2
+        pod/reader created
+        pod/reader condition met
+        reader scheduled on surviving node: k3s-prod-3 (victim was k3s-prod-2)
+        recovered='node-loss-canary-1789795346371286043' expected='node-loss-canary-1789795346371286043'
+        volume available + data intact from a surviving node
+        post-fault robustness[1]=healthy
+        NODE_LOSS_VOLUME_AVAILABLE_OK
+    l.go:52: | 05:23:37 | [32;1mnode-loss[0;22m | [32;1mvolume-stays-available-across-node-loss[0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 05:23:37 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mTRY[0;22m       | [36;1mEND[0;22m   |
+    l.go:52: | 05:23:37 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mFINALLY[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 05:23:37 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c set -uo pipefail
+        for n in $(kubectl get nodes -l "conformance.home.k3s/cordoned-by=$NAMESPACE" -o name 2>/dev/null); do
+          kubectl uncordon "${n#node/}" || true
+          kubectl label "$n" "conformance.home.k3s/cordoned-by-" || true
+          echo "restored node to service: ${n#node/}"
+        done
+    l.go:52: | 05:23:37 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        node/k3s-prod-2 uncordoned
+        node/k3s-prod-2 unlabeled
+        restored node to service: k3s-prod-2
+    l.go:52: | 05:23:37 | [32;1mnode-loss[0;22m | [32;1mvolume-stays-available-across-node-loss[0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 05:23:37 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mCMD[0;22m       | [36;1mRUN[0;22m   |
+        === COMMAND
+        /usr/bin/sh -c kubectl -n "$NAMESPACE" delete pod writer reader --ignore-not-found --wait=false || true
+        kubectl -n "$NAMESPACE" delete pvc survivor --ignore-not-found --wait=false || true
+        echo "cleanup best-effort; chainsaw namespace teardown finalizes"
+    l.go:52: | 05:23:38 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mSCRIPT[0;22m    | [36;1mLOG[0;22m   |
+        === STDOUT
+        pod "reader" deleted from chainsaw-advanced-boxer namespace
+        persistentvolumeclaim "survivor" deleted from chainsaw-advanced-boxer namespace
+        cleanup best-effort; chainsaw namespace teardown finalizes
+    l.go:52: | 05:23:38 | [32;1mnode-loss[0;22m | [32;1mvolume-stays-available-across-node-loss[0;22m | [32;1mSCRIPT[0;22m    | [32;1mDONE[0;22m  |
+    l.go:52: | 05:23:38 | [36;1mnode-loss[0;22m | [36;1mvolume-stays-available-across-node-loss[0;22m | [36;1mFINALLY[0;22m   | [36;1mEND[0;22m   |
+    l.go:52: | 05:23:38 | [36;1mnode-loss[0;22m | [36;1m@chainsaw                              [0;22m | [36;1mCLEANUP[0;22m   | [36;1mBEGIN[0;22m |
+    l.go:52: | 05:23:38 | [32;1mnode-loss[0;22m | [32;1m@chainsaw                              [0;22m | [32;1mDELETE[0;22m    | [32;1mOK[0;22m    | v1/Namespace @ chainsaw-advanced-boxer
+    l.go:52: | 05:24:21 | [36;1mnode-loss[0;22m | [36;1m@chainsaw                              [0;22m | [36;1mCLEANUP[0;22m   | [36;1mEND[0;22m   |
+--- PASS: chainsaw (0.00s)
+    --- PASS: chainsaw/node-loss (115.86s)
+PASS
+Tests Summary...
+- Passed  tests 1
+- Failed  tests 0
+- Skipped tests 0
+Done.
+merge_junit: merged 1 report(s) -> /work/conformance/_artifacts/report.junit.xml (tests=1 failures=0 errors=0 skipped=0)
+[1m[run.sh][0m Done. JUnit: /work/conformance/_artifacts/report.junit.xml | Coverage: /work/conformance/_artifacts/coverage/coverage.md
@@ -1,2 +1,8 @@
 {"chainsaw_version": "v0.2.12", "env": "dev", "git_sha": "57d4df8c4f992732a49f3e2daddcace866778ab0", "junit_result": "passed", "kube_version": "v1.36.4+k3s1", "layer": "L3", "note": "run log OUTPUT carries every declared pass token (NODE_LOSS_VOLUME_AVAILABLE_OK) and no skip token [log scoped to this testcase; tokens read from real-output sections only]", "proof": "proven", "requirements": ["R-STATE-02"], "run_id": "20260901T235117Z-e9a4b66", "sentinel": "NODE_LOSS_VOLUME_AVAILABLE_OK", "test": "node-loss", "ts_utc": "2026-09-01T23:51:17Z"}
 {"chainsaw_version": "v0.2.12", "env": "dev", "git_sha": "fdc3265585f4b775c0a6ae3fb33c837b0c643655", "junit_result": "passed", "kube_version": "v1.36.4+k3s1", "layer": "L3", "note": "run log OUTPUT carries every declared pass token (OFF_CLUSTER_TARGET_OK, BACKUPS_ARE_SCHEDULED_OK, DR_RESTORED_FROM_OFF_CLUSTER_BACKUP_OK) and no skip token [log scoped to this testcase; tokens read from real-output sections only]", "proof": "proven", "requirements": ["R-STATE-03"], "run_id": "20260902T001907Z-fdc3265", "sentinel": "DR_RESTORED_FROM_OFF_CLUSTER_BACKUP_OK", "test": "dr-restore", "ts_utc": "2026-09-02T00:19:07Z"}
+{"chainsaw_version": "v0.2.12", "env": "prod", "git_sha": "19fc8bcb27eab42a0007b28a831519d3e325c7b6", "junit_result": "passed", "kube_version": "v1.36.4+k3s1", "layer": "L1", "note": "L1 offline check exited 0; run_l1_offline.py renders its skips as JUnit <skipped/>, so a green JUnit is truthful without a sentinel", "proof": "proven", "requirements": ["R-NET-05", "R-NET-06", "R-NET-07"], "run_id": "20260913T014321Z-19fc8bc", "sentinel": null, "test": "egress-class-render", "ts_utc": "2026-09-13T01:43:21Z"}
+{"chainsaw_version": "v0.2.12", "env": "prod", "git_sha": "19fc8bcb27eab42a0007b28a831519d3e325c7b6-dirty", "junit_result": "passed", "kube_version": "v1.36.4+k3s1", "layer": "L3", "note": "run log OUTPUT carries every declared pass token (NS_PRIVILEGED_OK, TUNNEL_HEALTHY_OK, NO_LEAK_OK, INTERNET_UNAFFECTED_OK, TUNNEL_SELF_HEAL_OK, TUNNEL_RECOVERED_OK) and no skip token [log scoped to this testcase; tokens read from real-output sections only]", "proof": "proven", "requirements": ["R-NET-06"], "run_id": "20260913T014437Z-19fc8bc", "sentinel": "TUNNEL_RECOVERED_OK", "test": "vpn-killswitch", "ts_utc": "2026-09-13T01:44:37Z"}
+{"chainsaw_version": "v0.2.12", "env": "prod", "git_sha": "9d0814ae61e6a0ba64d3789a71f1cd9c985efbf0", "junit_result": "passed", "kube_version": "v1.36.4+k3s1", "layer": "L3", "note": "run log OUTPUT carries every declared pass token (NS_PRIVILEGED_OK, TUNNEL_HEALTHY_OK, NO_LEAK_OK, INTERNET_UNAFFECTED_OK, TUNNEL_SELF_HEAL_OK, TUNNEL_RECOVERED_OK) and no skip token [log scoped to this testcase; tokens read from real-output sections only]", "proof": "proven", "requirements": ["R-NET-06"], "run_id": "20260913T014923Z-9d0814a", "sentinel": "TUNNEL_RECOVERED_OK", "test": "vpn-killswitch", "ts_utc": "2026-09-13T01:49:23Z"}
+{"chainsaw_version": "v0.2.12", "env": "prod", "git_sha": "24b8111d0c39e9417e9f4d782f333f683540cfa7", "junit_result": "passed", "kube_version": "v1.36.4+k3s1", "layer": "L3", "note": "run log OUTPUT carries every declared pass token (OFF_CLUSTER_TARGET_OK, BACKUPS_ARE_SCHEDULED_OK, DR_RESTORED_FROM_OFF_CLUSTER_BACKUP_OK) and no skip token [log scoped to this testcase; tokens read from real-output sections only]", "proof": "proven", "requirements": ["R-STATE-03"], "run_id": "20260914T021505Z-24b8111", "sentinel": "DR_RESTORED_FROM_OFF_CLUSTER_BACKUP_OK", "test": "dr-restore", "ts_utc": "2026-09-14T02:15:05Z"}
+{"chainsaw_version": "v0.2.12", "env": "prod", "git_sha": "bd17b65db9fa906f336528e90b429ec1e2377963", "junit_result": "passed", "kube_version": "v1.36.4+k3s1", "layer": "L0", "note": "L0 offline check exited 0; run_l1_offline.py renders its skips as JUnit <skipped/>, so a green JUnit is truthful without a sentinel", "proof": "proven", "requirements": ["R-ENV-02", "R-STATE-03"], "run_id": "20260914T021902Z-bd17b65", "sentinel": null, "test": "placeholder-guard-coupling", "ts_utc": "2026-09-14T02:19:02Z"}
+{"chainsaw_version": "v0.2.12", "env": "prod", "git_sha": "9339d5a79e2301d399e4e20722b164583c53c55d", "junit_result": "passed", "kube_version": "v1.36.4+k3s1", "layer": "L3", "note": "run log OUTPUT carries every declared pass token (NODE_LOSS_VOLUME_AVAILABLE_OK) and no skip token [log scoped to this testcase; tokens read from real-output sections only]", "proof": "proven", "requirements": ["R-STATE-02"], "run_id": "20260919T052225Z-9339d5a", "sentinel": "NODE_LOSS_VOLUME_AVAILABLE_OK", "test": "node-loss", "ts_utc": "2026-09-19T05:22:25Z"}
@@ -0,0 +1,128 @@
+# =============================================================================
+# L0 STATIC — every metric an alert rule queries is CLAIMED by a scrape target this repo configures
+# Catalog: docs/14 L0 row ("Pre-apply, in CI") — runs WITHOUT a cluster.
+#
+# THE DEFECT THIS CLOSES. An alert rule whose metric is never scraped is not a broken alert — it is
+# an ABSENT alert that reads as a present one. `longhorn_volume_robustness == 2` over a TSDB with no
+# longhorn_* series returns no vector, so the rule is permanently quiet, permanently "healthy", and
+# indistinguishable from a correct rule on a healthy cluster. It survives review (the PromQL is
+# right), it survives `promtool test rules` (the unit test supplies the series itself), and it
+# survives every dashboard (nobody looks for a panel that was never built).
+#
+# MEASURED ON PROD, 2026-09-13, before this change — 13 rules across three families were inert:
+#   count(longhorn_volume_robustness)                        => (empty)   4 rules
+#   count({__name__=~"certmanager.*"})                       => (empty)   3 rules
+#   count(hubble_drop_total)                                 => (empty)   1 rule
+#   count by (job) (up)                                      => 20 jobs, none Longhorn/cert-manager/Hubble
+# So storage health was unmonitored on a cluster whose prod-1 had just had a failing SSD
+# (DECISIONS-LOG), TLS expiry was unmonitored with the live `wildcard-home` wildcard 89 days from
+# expiry, and the platform had no policy-drop visibility at all. The Flux family (gotk_*, 5 rules)
+# was the same defect and was fixed separately in a79693d.
+#
+# GIVEN every alerting rule in every PrometheusRule in the repo (platform/**, apps/wave-*),
+# WHEN  each rule's PromQL is parsed for the metric names it selects,
+# THEN  (1) every metric name is CLAIMED by exactly one declared scrape owner, and each owner's
+#           claim is PROVEN AGAINST THE REPO — the file that enables that scrape must still contain
+#           the enabling declaration, so deleting `metrics.serviceMonitor.enabled` from
+#           platform/longhorn/helmrelease.yaml fails this check instead of silently re-inerting four
+#           storage alerts;
+#       (2) an owner's NEGATIVE conditions hold too, where the enablement can be defeated without
+#           being deleted — cert-manager's chart calls `fail` if podmonitor and servicemonitor are
+#           both set, Longhorn's own NetworkPolicies drop the scrape unless
+#           networkpolicy-metrics.yaml is wired, and kube_node_labels does not exist at all unless
+#           kube-state-metrics' metricLabelsAllowlist names the label;
+#       (3) a metric with NO owner FAILS, unless it is declared in KNOWN_UNWIRED_METRICS — a
+#           shrink-only register (hubble_drop_total today, with the CNI-rollout reason recorded);
+#       (4) `up{job="X"}` is audited on its own axis, because `up` always exists and so the metric
+#           check above can never see this failure: where the repo authors a Service and a
+#           ServiceMonitor in the SAME file, the monitor's endpoint port must be a port that Service
+#           actually defines. All 12 apps/* `<app>-down` SLI rules used to fail this (the monitors
+#           named port `metrics`; no app Service defined one) and were registered in
+#           KNOWN_UNWIRED_JOBS with the live proof that their `up{job=...}` series did not exist.
+#           THAT REGISTER IS NOW EMPTY BECAUSE THE TWELVE RULES WERE FIXED, not waived: they read
+#           kube-state-metrics readiness of their own workload object instead (2026-09-13), the dead
+#           ServiceMonitors are gone, and so is this axis' only subject. The monitor side therefore
+#           moved into its own check — tests/l0-static/servicemonitor-ports-resolve — which needs no
+#           alert rule to reach a monitor, resolves by selector across the whole tree instead of by
+#           same-file adjacency, and proves its resolver on fixtures so it cannot pass merely for
+#           lack of subjects;
+#   AND (5) the check is LOAD-BEARING: this Test DECLARES `conformance.home.k3s/scope: whole-repo`,
+#           so ci/l0.sh Stage 3b's `--include-scope whole-repo` unions it into EVERY gate
+#           invocation, and ci/gate.sh blocks the merge when the l0 stage fails.
+#
+# WHY BOTH REGISTERS ARE RATCHETS AND NOT BLANKET FAILURES: the same reasoning as
+# alert-rules-unit-tested. Failing outright on the 12 app SLI rules would have made the gate red
+# until exporters existed for Plex, Pi-hole, Jackett, qBittorrent, Sonarr, Radarr, Seerr and friends
+# — none of which speak Prometheus natively — so the gate would have been disabled, and a disabled
+# gate protects nothing. Merely printing the gap is how these 13 rules stayed inert for three phases.
+# (The ratchet did its job: the twelve were closed a day later without an exporter, by reading a
+# signal that already existed. The register is empty now, and that is the outcome it was for.)
+# So each gap is DECLARED, counted on every run, and CANNOT GROW: a new alert on an unclaimed
+# metric FAILS, a new Service+ServiceMonitor pair with a mismatched port FAILS, and a STALE
+# register entry (the gap was closed, or the alert deleted) FAILS too, so neither register can rot
+# into fiction.
+#
+# STATUS: EXECUTABLE. `check.sh` is an offline assertion script (PyYAML, the same dependency as
+# catalog/render.py and dev-nodes-provisioned-as-code); conformance/run.sh --layer l0 and ci/l0.sh
+# run it directly, and this Chainsaw Test wraps the SAME script.
+#
+# NOT proven (all named in check.sh's header, which carries the full list). The one worth stating
+# here because it bit this very repo: an owner claims metrics by PREFIX, so this proves the SCRAPE
+# TARGET exists, never that the exporter emits that exact SERIES NAME.
+# `kubevirt_vmi_phase_count{phase="Failed"}` sat inside the scraped kubevirt_ family on an UP target
+# and did not exist at all on the deployed KubeVirt (corrected here to
+# `kubevirt_vmi_info{phase="failed"}`, lowercase — a capital-F matcher is equally inert). Catching
+# that needs the exporter's own metric list, i.e. a live read; it belongs to a future L1/L3 check
+# that diffs alert metrics against /api/v1/label/__name__/values.
+#
+# Also not proven: that a target is UP. This is static — it asserts the
+# enabling declaration is in git, never that the endpoint answers, that the chart still honours the
+# value key, or that a NetworkPolicy is sufficient. Those were established by live prod reads
+# recorded in the commit message (longhorn_volume_robustness 44 series, certmanager_* 104 series,
+# all six new targets up==1). It also cannot check a monitor whose Service comes from a Helm chart
+# rather than from this repo — the port name lives outside the tree — which is why (4) is scoped to
+# same-file Service+ServiceMonitor pairs. And it does not judge thresholds or reachability-to-human
+# (R-OBS-02 / the L3 alerting test).
+# =============================================================================
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: alert-metrics-have-scrape-targets
+  labels:
+    conformance.home.k3s/R-OBS-04: "true"
+  annotations:
+    conformance.home.k3s/requirements: "R-OBS-04"
+    conformance.home.k3s/layer: "L0"
+    # WHOLE-REPO SCOPE — this invariant quantifies over every PrometheusRule in the tree AND over
+    # every scrape-enabling declaration that feeds them, which live in eight different components
+    # (platform/monitoring, platform/longhorn, platform/cert-manager, platform/velero,
+    # platform/kubevirt, platform/keycloak, platform/cnpg, apps/wave-*). No single requirement
+    # path-maps to that set.
+    #
+    # WHY IT MUST NOT BE REQUIREMENT-SCOPED: ci/touched-requirements.sh maps apps/* to NOTHING and
+    # platform/monitoring/* to R-OBS-01/R-OBS-02 — not R-OBS-04. A change that adds an alert under
+    # apps/ or platform/kubevirt/, or one that flips a chart's `serviceMonitor.enabled` back to
+    # false under platform/longhorn/, therefore attributes a requirement set that would FILTER THIS
+    # CHECK OUT of exactly the change that re-inerts the alerts. Declaring the scope makes
+    # ci/l0.sh Stage 3b union it into every run instead, and makes an honest SKIP loud (rc 3 =
+    # UNWIRED, never green) rather than silently green.
+    conformance.home.k3s/scope: "whole-repo"
+    conformance.home.k3s/safety-critical: "false"
+    conformance.home.k3s/executable: "true"
+    conformance.home.k3s/intent: >-
+      Every metric name queried by every alert rule is claimed by a scrape target whose enabling
+      declaration is still present in this repo, every `up{job=...}` selector names a job a repo
+      monitor can actually produce, and the two gaps that remain are enumerated in registers that
+      can only shrink — so an alert can never again be authored, reviewed and merged against a
+      metric nothing scrapes.
+spec:
+  steps:
+    - name: audit-every-alert-metric-against-the-configured-scrape-targets
+      description: >-
+        Parse every metric name out of every alerting rule, resolve each against the declared
+        scrape-owner table, prove each owner's enabling declaration (and its negative conditions)
+        still hold in git, audit `up{job=...}` against same-file Service/ServiceMonitor port
+        agreement, and ratchet both registers of declared gaps.
+      try:
+        - script:
+            content: bash ./check.sh
@@ -0,0 +1,739 @@
+#!/usr/bin/env bash
+# =============================================================================
+# L0 static check (offline, no cluster) — alert-metrics-have-scrape-targets
+# Serves: R-OBS-04 ("The platform alerts on its own health (nodes, storage, GitOps, certs,
+#         VPN)." — spec docs/10-observability-and-alerting.md)
+#
+# WHY THIS EXISTS — AN ALERT ON AN UNSCRAPED METRIC IS AN ABSENT ALERT THAT READS AS A PRESENT ONE
+# -----------------------------------------------------------------------------------------------
+# `longhorn_volume_robustness == 2` evaluated against a TSDB that holds no longhorn_* series
+# returns no vector. The rule is therefore permanently quiet, permanently "healthy", and
+# INDISTINGUISHABLE from a correct rule on a healthy cluster. It passes review (the PromQL is
+# right). It passes `promtool test rules` (the unit test supplies the series itself, so a unit
+# test proves nothing about whether anything scrapes them). It shows up on no dashboard, because
+# nobody looks for a panel that was never built.
+#
+# Measured on prod 2026-09-13, BEFORE the change that added this check — 13 rules were inert:
+#   count(longhorn_volume_robustness)            => (empty)    LonghornVolumeDegraded/Faulted/
+#                                                              CapacityHigh, LonghornNodeStorageHigh
+#   count({__name__=~"certmanager.*"})           => (empty)    CertificateExpiringSoon/
+#                                                              ExpiryImminent/NotReady
+#   count(hubble_drop_total)                     => (empty)    HubbleDeniedFlowSpike
+#   count by (job) (up)                          => 20 jobs, none Longhorn, cert-manager or Hubble
+# Storage health was unmonitored on the cluster whose prod-1 had just had a failing SSD; TLS
+# expiry was unmonitored with the live `wildcard-home` wildcard 89 days out; there was no
+# policy-drop visibility at all. The gotk_* family (5 more rules) was the same defect, fixed
+# separately in a79693d.
+#
+# WHAT MAKES THIS CLASS DIFFERENT from the two failure modes alert-rules-unit-tested catches: a
+# permanently-firing rule is loud, and a rule that behaves wrongly against synthetic series is
+# caught by promtool. This one is caught by NEITHER, because the missing thing is not in the rule
+# file at all — it is a `serviceMonitor.enabled` that was never set in a completely different
+# component's HelmRelease. So the audit has to cross from the alert to the scrape config, which is
+# what the owner table below does.
+#
+# GIVEN every alerting rule in every PrometheusRule in the repo,
+# WHEN  each rule's PromQL is parsed for the metric names it selects,
+# THEN  (1) every metric name is CLAIMED by exactly one declared owner in SCRAPE_OWNERS, and the
+#           owner's `require` regexes still match its file — so deleting the enablement from
+#           platform/longhorn/helmrelease.yaml FAILS here instead of silently re-inerting four
+#           storage alerts;
+#       (2) each owner's `forbid` regexes do NOT match, for the cases where the enablement can be
+#           defeated without being deleted (cert-manager's chart `fail`s if podmonitor and
+#           servicemonitor are both enabled; an `enabled: false` inside the exporter's own block);
+#       (3) a metric with no owner FAILS unless declared in KNOWN_UNWIRED_METRICS (shrink-only);
+#       (4) `up{job="X"}` is audited separately — `up` itself always exists, so (1) is blind to
+#           this — by requiring that where this repo authors a Service and a ServiceMonitor in the
+#           SAME file, the monitor's endpoint port is a port that Service actually defines;
+#           violations must be declared in KNOWN_UNWIRED_JOBS (shrink-only);
+#   AND (5) the check is LOAD-BEARING: this test declares `conformance.home.k3s/scope: whole-repo`
+#           so ci/l0.sh unions it into every gate run, and ci/gate.sh blocks on an l0 failure.
+#
+# WHY THE REGISTERS ARE RATCHETS (the decision and its reasons) — the same three options as
+# alert-rules-unit-tested faced:
+#   * FAIL outright on all 13: correct in principle, but 12 of them are app SLI rules that need
+#     Prometheus exporters for Plex, Pi-hole, Jackett, qBittorrent, Sonarr, Radarr and Seerr —
+#     none of which speak Prometheus natively. The gate would be red for every change until that
+#     work lands, so it would get disabled, and a disabled gate protects nothing.
+#   * merely REPORT: that is precisely how these rules stayed inert across phases 4-6.
+#   * RATCHET (chosen): each gap is declared here, printed with counts on every run, and CANNOT
+#     GROW. A new alert on an unclaimed metric FAILS. A new same-file Service+ServiceMonitor pair
+#     with a mismatched port FAILS. A STALE entry — the gap was closed, or the alert deleted —
+#     also FAILS, so neither register can rot into fiction.
+#
+# WHAT THIS DOES *NOT* PROVE (honest gaps — this is a STATIC check):
+#   - It does not prove a target is UP, that an endpoint answers, that the chart still honours the
+#     values key, or that a NetworkPolicy is sufficient. Those were established by live prod reads
+#     recorded in the commit message: with the enablements applied, longhorn_volume_robustness
+#     returned 44 series, {__name__=~"certmanager.*"} returned 104, and all six new targets read
+#     up==1. A live probe needs a cluster, which L0 by definition does not have.
+#   - It cannot audit a ServiceMonitor whose Service is created by a Helm chart rather than by this
+#     repo: the port name lives outside the tree. That is why (4) is scoped to same-file
+#     Service+ServiceMonitor pairs — the apps/* ServiceDefinition pattern — and why the
+#     platform/* monitors (oauth2-proxy, kubevirt, keycloak, flux) are out of its reach. Their
+#     liveness is covered by the fact that their metrics have owners under (1).
+#   - IT PROVES THE SCRAPE TARGET, NOT THE SERIES NAME. An owner claims a metric by PREFIX, so a
+#     metric in a scraped family whose exact name the exporter does not emit still passes. This is
+#     a real residual hole and it was live in this repo: `kubevirt_vmi_phase_count{phase="Failed"}`
+#     (KubeVirtVMLaunchFailing) sat inside the scraped `kubevirt_` family on an UP target, and the
+#     series simply does not exist on the deployed KubeVirt — verified on prod 2026-09-13, where the
+#     only kubevirt_vmi_* names are `info` and `number_of_outdated`, and the only phase-bearing
+#     names are the phase_transition_time histograms. Corrected in the same change to
+#     `kubevirt_vmi_info{phase="failed"}` (note the LOWERCASE value KubeVirt writes: a capital-F
+#     matcher selects nothing and is just as inert). Catching that class needs the exporter's own
+#     metric list, which is a live read, not a static one — it belongs to a future L1/L3 check that
+#     diffs every alert metric against `/api/v1/label/__name__/values`. The same limit applies to
+#     every LABEL VALUE an alert matches on.
+#   - The metric-name parser is a PromQL approximation, not a parser: it strips string literals,
+#     label-matcher bodies and aggregation label lists, then treats remaining bare identifiers as
+#     metric selectors. A metric referenced ONLY through a `{__name__=~"..."}` regex selector would
+#     be missed. No rule in this repo does that, and assertion (0) fails if the parser stops
+#     finding metrics at all.
+#   - It does not judge thresholds, and does not prove an alert reaches a human (R-OBS-02 and the
+#     L3 alerting test own that).
+#   - It does not read ../home-network-k3s. The spec is read-only (R-TEST-06).
+#
+# Exit 0 = all assertions pass. Exit 1 = a failure. Exit 3 (honest SKIP, and because this test
+# declares the whole-repo scope the runner turns it into rc 3 = UNWIRED, never green) only if the
+# repo contains no PrometheusRule at all — i.e. there is genuinely nothing to audit.
+# =============================================================================
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "${DIR}/../../../.." && pwd)"        # repo root
+PYTHON="${PYTHON:-python3}"
+
+# Honest SKIP (never green for a scope-declaring test) if there is nothing to audit at all.
+if ! grep -rl 'kind: PrometheusRule' "${ROOT}/platform" "${ROOT}/apps" >/dev/null 2>&1; then
+  echo "check SKIPPED: no PrometheusRule found under platform/ or apps/ — no alert rules to audit" >&2
+  exit 3
+fi
+
+cd "${ROOT}"
+"${PYTHON}" - "${ROOT}" <<'PY'
+"""Static audit: every alert rule's metrics are claimed by a scrape target this repo configures.
+
+PyYAML is used deliberately rather than the line-based parsing the neighbouring checks favour:
+alert `expr:` values are multi-line block scalars, and a line-based reader of PromQL would be the
+kind of approximate parser that silently stops matching — the exact failure class this check
+exists to prevent. Same dependency as catalog/render.py and dev-nodes-provisioned-as-code.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:                                  # pragma: no cover
+    print("check FAIL: PyYAML is required (same dependency as catalog/render.py)",
+          file=sys.stderr)
+    raise SystemExit(1)
+
+ROOT = Path(sys.argv[1])
+sys.dont_write_bytecode = True          # keep __pycache__ out of the tracked tree
+
+FAILURES: list[str] = []
+CHECKS = 0
+
+
+def check(cond, msg):
+    global CHECKS
+    CHECKS += 1
+    if not cond:
+        FAILURES.append(msg)
+
+
+def read(p: Path) -> str:
+    try:
+        return p.read_text()
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+# =============================================================================================
+# THE DECLARED SCRAPE-OWNER TABLE (assertions 1 and 2).
+#
+# Each entry claims a set of metric names (exact names and/or prefixes) and names the file whose
+# declaration is what makes those metrics exist in the TSDB, plus the regexes that prove it. This
+# is the crossing from "an alert queries X" to "something in this repo scrapes X", and it is the
+# part that makes the check a REGRESSION guard rather than a one-time audit: every `require`
+# regex is re-evaluated against the working tree on every gate run.
+#
+# `require`  — ALL must match the file. The enablement itself.
+# `forbid`   — NONE may match. For enablements that can be defeated without being deleted.
+#
+# Longest prefix wins, so kube_velero_schedule_ is resolved before kube_.
+# =============================================================================================
+KPS = "platform/monitoring/kube-prometheus-stack.yaml"
+
+SCRAPE_OWNERS: list[dict] = [
+    {
+        "owner": "kube-prometheus-stack: bundled node-exporter DaemonSet + its ServiceMonitor",
+        "prefixes": ("node_",),
+        "file": KPS,
+        # The subchart block must be present and configured here (it is where the exporter's
+        # resources live). The chart default is enabled:true, so the regression to guard is a
+        # DISABLE, not a missing enable.
+        "require": [r"^\s*prometheus-node-exporter:\s*$"],
+        "forbid": [r"prometheus-node-exporter:\s*\n(?:\s*#[^\n]*\n)*\s*enabled:\s*false"],
+        "why": "node_* powers all seven platform-health.nodes rules including the two IO-pressure "
+               "rules that exist because of prod-1's etcd WAL starvation",
+    },
+    {
+        "owner": "kube-prometheus-stack: the kubelet ServiceMonitor (cAdvisor + volume stats)",
+        # container_* is cAdvisor, which the kubelet ServiceMonitor scrapes on the SAME target as
+        # kubelet_* via its /metrics/cadvisor path (this entry's title always said so; the prefix
+        # was added 2026-09-14 when ContainerIOStallHigh became the first rule to query it).
+        # Verified on prod: container_pressure_io_stalled_seconds_total, 405 series across the
+        # three nodes, job="kubelet", metrics_path="/metrics/cadvisor".
+        "prefixes": ("kubelet_", "container_"),
+        "file": KPS,
+        # Chart default kubelet.enabled:true. There is no explicit enable to require, so the only
+        # honest assertion is that it has not been turned off the way kubeProxy/kubeEtcd were.
+        "require": [r"kubeProxy:"],   # sentinel: the exporter-toggle block is still authored here
+        "forbid": [r"\n\s*kubelet:\s*\n(?:\s*#[^\n]*\n)*\s*enabled:\s*false"],
+        "why": "kubelet_volume_stats_* powers MonitoringVolumeFillingUp and all three "
+               "pvc-capacity-alerts rules; container_pressure_io_stalled_seconds_total is the "
+               "only signal on this cluster that can name WHICH workload an I/O stall is hitting",
+    },
+    {
+        "owner": "kube-prometheus-stack: the kube-apiserver ServiceMonitor (chart default, NOT "
+                 "disabled the way kubeEtcd/kubeProxy are)",
+        # DELIBERATELY EXACT NAMES, NOT AN `etcd_` PREFIX. On this cluster the only etcd-shaped
+        # metrics that exist are the APISERVER'S CLIENT-SIDE view of its own local member. etcd's
+        # server-side disk metrics (etcd_disk_wal_fsync_duration_seconds,
+        # etcd_disk_backend_commit_duration_seconds) are NOT scraped — kubeEtcd.enabled:false for
+        # k3s' embedded etcd — and verified absent on prod 2026-09-14: a query for
+        # {__name__=~"etcd_disk_.*|etcd_server_.*|etcd_mvcc_.*"} returns nothing at all. A blanket
+        # `etcd_` claim would let a future rule on those names pass this check while being inert,
+        # which is precisely the hole this test exists to close. Widen only with a real scrape.
+        "exact": (
+            "etcd_request_duration_seconds_bucket",
+            "etcd_request_duration_seconds_count",
+        ),
+        "file": KPS,
+        "require": [r"kubeProxy:"],   # sentinel: the exporter-toggle block is still authored here
+        "forbid": [r"\n\s*kubeApiServer:\s*\n(?:\s*#[^\n]*\n)*\s*enabled:\s*false"],
+        "why": "etcd_request_duration_seconds_* is the ONLY per-node view of the etcd storage path "
+               "this cluster has, and NodeEtcdRequestsSlow is the only alert that can see the "
+               "condition that took k3s-prod-1 NotReady on 2026-09-07 before the node drops",
+    },
+    {
+        "owner": "kube-prometheus-stack: kube-state-metrics custom-resource-state for Velero Schedules",
+        "prefixes": ("kube_velero_schedule_",),
+        "file": KPS,
+        "require": [
+            r"customResourceState:\s*\n\s*enabled:\s*true",
+            r"metricNamePrefix:\s*kube_velero_schedule",
+            # The RBAC is MANDATORY, not cosmetic: without velero.io read access KSM emits the
+            # custom-resource-state metrics as an EMPTY SET and logs a forbidden error — silent,
+            # and the inert-alert failure mode all over again (measured; see the block's header).
+            r'apiGroups:\s*\["velero\.io"\]',
+            r'resources:\s*\["schedules"\]',
+        ],
+        "forbid": [r"customResourceState:\s*\n\s*enabled:\s*false"],
+        "why": "kube_velero_schedule_* is the only thing that can see a Schedule that has NEVER "
+               "backed up (VeleroScheduleNeverBackedUp / SchedulePaused / NoVolumeDataBackup); "
+               "Velero itself publishes nothing until a backup is attempted",
+    },
+    {
+        "owner": "kube-prometheus-stack: bundled kube-state-metrics",
+        "prefixes": ("kube_",),
+        "file": KPS,
+        "require": [r"^\s*kube-state-metrics:\s*$"],
+        "forbid": [r"kube-state-metrics:\s*\n(?:\s*#[^\n]*\n)*\s*enabled:\s*false"],
+        # kube_node_labels is a SPECIAL CASE and is checked on its own below: KSM exposes no
+        # custom node labels by default, so the metric does not exist unless metricLabelsAllowlist
+        # names the label. The prefix claim alone would pass while VPNTunnelDown's join matched
+        # nothing.
+        "why": "kube_* powers the Keycloak, KubeVirt-crashloop, CNPG-colocation and Velero-schedule "
+               "rules",
+    },
+    {
+        "owner": "kube-state-metrics metricLabelsAllowlist (the egress-gateway node label)",
+        "exact": ("kube_node_labels",),
+        "file": KPS,
+        "require": [
+            r"metricLabelsAllowlist:",
+              # The label must be IN the allowlist, not BE the whole allowlist. This pattern used to
+              # end in a literal `]`, asserting the list held exactly this one label — so adding a
+              # second one (`egress-uplink`, for the steering-staleness alerts) made this check FAIL
+              # while the property it guards stayed perfectly satisfied. A guard that breaks when you
+              # correctly extend the thing it guards teaches people to edit the guard, which is how it
+              # stops guarding. `[,\\]]` accepts either the end of the list or a further entry.
+              r"nodes=\[homelab\.keithjackson\.dev/egress-gateway[,\]]",
+        ],
+        "forbid": [],
+        "why": "KSM exposes NO custom labels by default. Without the allowlist entry "
+               "kube_node_labels carries no egress-gateway label and VPNTunnelDown's join silently "
+               "matches nothing — a rule that is present, evaluating, and structurally inert",
+    },
+    {
+        "owner": "CNPG: enablePodMonitor on the Cluster CRs (the operator renders one PodMonitor each)",
+        "prefixes": ("cnpg_",),
+        "file": "platform/keycloak/postgres-cluster.yaml",
+        "require": [r"^\s*enablePodMonitor:\s*true\s*$"],
+        "forbid": [],
+        "why": "cnpg_* powers all six platform-health.cnpg rules, including the WAL-archive backlog "
+               "and no-recoverability-point rules that guard R-STATE-03",
+    },
+    {
+        "owner": "Flux controllers: platform/monitoring/flux-podmonitor.yaml (merged a79693d)",
+        "prefixes": ("gotk_",),
+        "file": "platform/monitoring/flux-podmonitor.yaml",
+        "require": [r"kind:\s*PodMonitor", r"port:\s*http-prom"],
+        "forbid": [],
+        "why": "gotk_* powers FluxReconciliationFailure, FluxResourceSuspended and the three "
+               "automated-update rules — on a platform whose entire delivery model is Flux",
+    },
+    {
+        "owner": "cert-manager: prometheus.servicemonitor.enabled in the HelmRelease",
+        "prefixes": ("certmanager_",),
+        "file": "platform/cert-manager/helmrelease.yaml",
+        "require": [r"prometheus:\s*\n\s*servicemonitor:\s*\n\s*enabled:\s*true"],
+        # The chart calls `fail` when both monitor kinds are enabled, which would break the whole
+        # HelmRelease rather than just the scrape. Measured against v1.21.2.
+        "forbid": [r"podmonitor:\s*\n\s*enabled:\s*true"],
+        "why": "certmanager_* powers CertificateExpiringSoon / ExpiryImminent / NotReady — the only "
+               "warning that an ACME DNS-01 renewal of the live wildcard has quietly failed",
+    },
+    {
+        "owner": "Longhorn: metrics.serviceMonitor.enabled in the HelmRelease",
+        "prefixes": ("longhorn_",),
+        "file": "platform/longhorn/helmrelease.yaml",
+        "require": [r"metrics:\s*\n\s*serviceMonitor:\s*\n\s*enabled:\s*true"],
+        "forbid": [],
+        "why": "longhorn_* powers the four storage rules on a cluster whose recurring failure mode "
+               "is a disk",
+        # The ServiceMonitor ALONE is not sufficient here — see the companion assertion below.
+        "companion": {
+            "file": "platform/longhorn/kustomization.yaml",
+            "require": [r"^\s*-\s*networkpolicy-metrics\.yaml\s*$"],
+            "why": "Longhorn 1.12.1 ships its own effectively-unconditional NetworkPolicies "
+                   "(guarded on networkPolicies.restrictInternalTraffic, default true — NOT on "
+                   "networkPolicies.enabled) whose longhorn-manager policy admits only other "
+                   "Longhorn components in the same namespace. MEASURED on prod: with the "
+                   "ServiceMonitor applied and no allowance, all three targets were DISCOVERED and "
+                   "every scrape failed with 'context deadline exceeded' after 10.0s — a drop, not "
+                   "a refusal — and the TSDB stayed empty. So without networkpolicy-metrics.yaml "
+                   "the four storage alerts are inert even though the monitor exists",
+        },
+    },
+    {
+        "owner": "KubeVirt/CDI: platform/kubevirt/servicemonitor.yaml",
+        "prefixes": ("kubevirt_",),
+        "file": "platform/kubevirt/servicemonitor.yaml",
+        "require": [r"kind:\s*ServiceMonitor", r"port:\s*metrics"],
+        "forbid": [],
+        "why": "kubevirt_* powers the four platform-health.kubevirt rules (note the CDI rules use "
+               "the kubevirt_cdi_* names, not bare cdi_*)",
+    },
+    {
+        "owner": "Velero: metrics.serviceMonitor.enabled in the HelmRelease",
+        "prefixes": ("velero_",),
+        "file": "platform/velero/helmrelease.yaml",
+        "require": [r"metrics:\s*\n\s*serviceMonitor:\s*\n\s*enabled:\s*true"],
+        "forbid": [],
+        "why": "velero_* powers VeleroBackupFailure / PartialFailure / NoRecentBackup — the rules "
+               "that failed to notice prod running with zero volume backups",
+    },
+]
+
+# `up` is produced by EVERY scrape target, so no owner can meaningfully claim it and assertion (1)
+# is structurally blind to `up{job="X"}` naming a job nothing produces. That axis is assertion (4).
+UNIVERSAL = {"up"}
+
+# =============================================================================================
+# REGISTER 1 — KNOWN_UNWIRED_METRICS. Shrink-only. A metric here is queried by an alert and
+# claimed by NOTHING, so that alert is inert and the platform is blind to what it describes.
+# Removing an entry means wiring the scrape. An entry that stops being referenced by any alert,
+# or that gains an owner, FAILS as stale.
+# =============================================================================================
+KNOWN_UNWIRED_METRICS: dict[str, str] = {
+    "hubble_drop_total":
+        "HubbleDeniedFlowSpike — the platform has NO policy-drop / NetworkPolicy-regression "
+        "visibility. Unlike Longhorn and cert-manager (whose charts already serve /metrics and "
+        "only lacked a ServiceMonitor) Hubble publishes NOTHING to scrape until it is switched on "
+        "in Cilium's own config: platform/cilium/helmrelease.yaml sets hubble.{enabled,relay,ui} "
+        "but not hubble.metrics.enabled, and not prometheus.enabled for the agent. Turning them on "
+        "OPENS PORT 9965 ON EVERY cilium-agent AND ROLLS THE CNI DaemonSet across all three nodes "
+        "— the single most dangerous rollout on this cluster (the 2026-09-01 k8sServiceHost outage; "
+        "cilium was moved to its own Flux Kustomization precisely to isolate that blast radius) — "
+        "and requires a matching edit to roles/cilium/templates/cilium-values.yaml.j2 in the same "
+        "commit or a rebuilt node's bootstrap CNI config silently disagrees with the reconciled "
+        "one. Deliberately DEFERRED to its own change with a one-node canary; see the rule's "
+        "header in platform/monitoring/alerts.yaml.",
+}
+
+# =============================================================================================
+# REGISTER 2 — KNOWN_UNWIRED_JOBS. Shrink-only, and NOW EMPTY.
+#
+# Each entry was a `up{job="X"}` selector whose monitor named an endpoint port the Service it
+# selects did not define, so the monitor discovered ZERO targets, no `up{job="X"}` series existed,
+# and `up{job="X"} == 0` could never fire. The nastiest variant of the class: `up` exists in
+# abundance, so nothing about the metric name looks wrong, and `PrometheusTargetsMissing` cannot see
+# it either — a target that was never discovered has no up series to be 0.
+#
+# IT HELD ALL TWELVE apps/* SLI RULES, AND IT IS EMPTY BECAUSE THEY WERE FIXED, not because the gap
+# was waived (2026-09-13, branch fix/app-sli-rules-discover-no-targets). The register's own note
+# said closing it needed "a Prometheus exporter per app". That was the wrong conclusion from a true
+# premise: Plex, Pi-hole, Jackett, qBittorrent, Sonarr, Radarr, Seerr, Semaphore and Nextcloud
+# genuinely export no Prometheus metrics, so instead the `up` SLI was rewritten against a signal that
+# DOES exist for every workload — kube-state-metrics readiness of the service's own workload object
+# (`kube_deployment_status_replicas_available` / `kube_statefulset_status_replicas_ready`), and
+# `kubevirt_vmi_info{phase="running"}` for the VM. No exporter, no new scrape target; each rule is
+# unit-tested firing AND quiet (apps/wave-*/tests/app-slis.test.yaml) and each expression was
+# evaluated live on prod, where eleven of the twelve return no series on a healthy cluster and the
+# twelfth (vm-demo) is not deployed at all.
+#
+# The rendered ServiceMonitors went with them: a monitor for a workload that serves no metrics is
+# dead configuration that reads as coverage. So assertion (4) below now has NOTHING to audit under
+# apps/ — which is why the monitor-side axis moved into its own check,
+# tests/l0-static/servicemonitor-ports-resolve. THAT is where a ServiceMonitor naming a port no
+# Service defines fails, with no alert rule required, resolving by selector across the whole tree
+# rather than by same-file adjacency, and with its resolver proven on fixtures so it cannot pass for
+# lack of subjects. Keeping this register non-empty as "documentation" of a closed gap is exactly the
+# fiction the ratchet forbids: the stale-entry assertion below would fail, and rightly.
+# =============================================================================================
+KNOWN_UNWIRED_JOBS: dict[str, str] = {}
+
+# =============================================================================================
+# (0) PARSE EVERY ALERT RULE
+# =============================================================================================
+# PromQL metric-name approximation. Documented as a gap in the header: string literals,
+# label-matcher bodies and aggregation/vector-matching label lists are stripped first, then every
+# remaining bare identifier that is not a PromQL keyword or function is treated as a metric
+# selector. Assertion (0b) fails loudly if this stops finding metrics at all, which is the way an
+# approximate parser silently stops guarding.
+PROMQL_KEYWORDS = set("""
+abs absent absent_over_time ceil changes clamp clamp_max clamp_min day_of_month day_of_week
+day_of_year days_in_month delta deriv exp floor histogram_quantile histogram_count histogram_sum
+histogram_fraction histogram_stddev histogram_stdvar holt_winters hour idelta increase irate
+label_join label_replace ln log2 log10 minute month predict_linear rate resets round scalar sgn
+sort sort_desc sort_by_label sort_by_label_desc sqrt time timestamp vector year avg count
+count_values group max min quantile stddev stdvar sum topk bottomk limitk limit_ratio
+last_over_time avg_over_time min_over_time max_over_time sum_over_time count_over_time
+quantile_over_time stddev_over_time stdvar_over_time present_over_time mad_over_time
+double_exponential_smoothing info ts_of_max_over_time ts_of_min_over_time ts_of_last_over_time
+by without on ignoring group_left group_right offset bool and or unless if atan2 start end
+inf nan NaN Inf
+""".split())
+
+IDENT_RE = re.compile(r"(?<![\w:.])([a-zA-Z_:][a-zA-Z0-9_:]*)")
+UP_JOB_RE = re.compile(r"""\bup\s*\{[^}]*\bjob\s*=\s*["']([^"']+)["']""")
+
+
+def metric_names(expr: str) -> list[str]:
+    e = re.sub(r'"(?:[^"\\]|\\.)*"', '""', expr)
+    e = re.sub(r"'(?:[^'\\]|\\.)*'", "''", e)
+    e = re.sub(r"`(?:[^`\\]|\\.)*`", "``", e)
+    e = re.sub(r"\{[^{}]*\}", " ", e)               # label matchers
+    for _ in range(6):                               # nested aggregations
+        e = re.sub(r"\b(?:by|without|on|ignoring|group_left|group_right)\s*\([^()]*\)", " ", e)
+    out, seen = [], set()
+    for m in IDENT_RE.finditer(e):
+        n = m.group(1)
+        if n in PROMQL_KEYWORDS or re.fullmatch(r"\d+[smhdwy]?", n) or n in seen:
+            continue
+        seen.add(n)
+        out.append(n)
+    return out
+
+
+def is_golden_fixture(p: Path) -> bool:
+    """conformance/tests/**/golden/** holds EXPECTED-OUTPUT fixtures, not deployed manifests.
+
+    conformance/tests/l1-rendering/egress-class-render/golden/*.expected.yaml each contain a
+    rendered `<app>-down` PrometheusRule. They are the assertion data of another test, never
+    reconciled into a cluster, so auditing their scrape targets would be auditing a copy — the
+    same "reference, not declaration" distinction ci/touched-requirements.sh draws for ci/tests/
+    fixture paths. The templates they are rendered FROM are audited through apps/ and catalog/.
+    """
+    parts = p.parts
+    return "conformance" in parts and "golden" in parts
+
+
+# NESTED WORKTREES: skip dot-DIRECTORIES (.git, .claude) while still matching dot-FILES such
+# as .sops.yaml. .claude/worktrees/agent-*/ holds full repo copies for isolated agent runs, so
+# a bare rglob from ROOT audited up to 18 duplicates of every file — which both invents FAILs
+# and, worse, can satisfy an "something declares X" check from a copy rather than real source.
+# Same fix as egress-paths-selected-by-rules. .claude/ is gitignored (.gitignore:43).
+rule_files = sorted(
+    p for p in ROOT.rglob("*.yaml")
+    if not any(part.startswith(".") for part in p.relative_to(ROOT).parent.parts) and not is_golden_fixture(p) and "kind: PrometheusRule" in read(p)
+)
+check(len(rule_files) > 0,
+      "no file declaring `kind: PrometheusRule` found — the parser or the repo layout changed; "
+      "this check would silently audit nothing")
+
+# metric -> [ "<relpath>:<alert>", ... ] ; and the same shape for up{job="X"} selectors
+refs: dict[str, list[str]] = {}
+job_refs: dict[str, list[str]] = {}
+n_rules = 0
+for f in rule_files:
+    rel = str(f.relative_to(ROOT))
+    try:
+        docs = list(yaml.safe_load_all(read(f)))
+    except yaml.YAMLError as exc:
+        check(False, f"{rel} is not parseable YAML ({exc}); every alert in it is unaudited")
+        continue
+    for d in docs:
+        if not isinstance(d, dict) or d.get("kind") != "PrometheusRule":
+            continue
+        for grp in (d.get("spec") or {}).get("groups") or []:
+            for r in grp.get("rules") or []:
+                if "alert" not in r:
+                    continue                         # recording rules: not this check's subject
+                n_rules += 1
+                site = f"{rel}:{r['alert']}"
+                expr = str(r.get("expr", ""))
+                for n in metric_names(expr):
+                    refs.setdefault(n, []).append(site)
+                for j in UP_JOB_RE.findall(expr):
+                    job_refs.setdefault(j, []).append(site)
+
+check(n_rules > 0,
+      "no alerting rule parsed out of any PrometheusRule — the parse contract broke and this "
+      "check would pass vacuously while every alert's metric went unaudited")
+check(len(refs) >= 20,
+      f"only {len(refs)} distinct metric name(s) parsed out of {n_rules} alerting rule(s). The "
+      f"PromQL approximation has stopped matching — which is exactly how an approximate parser "
+      f"turns into a guard that passes while checking nothing. Fix metric_names() or replace it "
+      f"with a real parser")
+
+# =============================================================================================
+# (1)(2) RESOLVE EVERY METRIC TO AN OWNER, AND PROVE THE OWNER'S CLAIM AGAINST THE REPO
+# =============================================================================================
+def resolve(metric: str) -> dict | None:
+    """Longest-prefix / exact-name match against SCRAPE_OWNERS."""
+    best, best_len = None, -1
+    for o in SCRAPE_OWNERS:
+        if metric in o.get("exact", ()):            # exact names win outright
+            return o
+        for pfx in o.get("prefixes", ()):
+            if metric.startswith(pfx) and len(pfx) > best_len:
+                best, best_len = o, len(pfx)
+    return best
+
+
+# Every owner's FILE must exist, whether or not a metric currently lands on it: an owner pointing
+# at a deleted file is a claim nothing backs.
+for o in SCRAPE_OWNERS:
+    check((ROOT / o["file"]).is_file(),
+          f"SCRAPE_OWNERS names {o['file']} as the scrape owner for "
+          f"{o.get('prefixes') or o.get('exact')}, and that file does not exist in this repo — the "
+          f"claim is unbacked and the alerts that depend on it are inert")
+
+claimed: dict[str, dict] = {}
+unowned: list[str] = []
+for metric in sorted(refs):
+    if metric in UNIVERSAL:
+        continue
+    o = resolve(metric)
+    if o is None:
+        if metric in KNOWN_UNWIRED_METRICS:
+            continue                                 # declared gap; ratcheted below
+        unowned.append(metric)
+        check(False,
+              f"alert metric `{metric}` (queried by {', '.join(sorted(set(refs[metric])))}) is "
+              f"claimed by NO entry in SCRAPE_OWNERS. Nothing in this repo configures a scrape "
+              f"that produces it, so every rule above is STRUCTURALLY INERT: it evaluates to no "
+              f"vector, stays silent forever, and is indistinguishable from a healthy result. "
+              f"Either wire the scrape and add the owner entry, or — if it cannot be wired yet — "
+              f"declare it in KNOWN_UNWIRED_METRICS with the reason, so the gap is reported "
+              f"instead of silent")
+        continue
+    check(metric not in KNOWN_UNWIRED_METRICS,
+          f"`{metric}` is listed in KNOWN_UNWIRED_METRICS but is now claimed by "
+          f"{o['owner']} — the register is shrink-only: delete the entry so the next real gap is "
+          f"the one that shows up")
+    claimed[metric] = o
+
+# The owners that are actually load-bearing right now get their declarations verified.
+for o in SCRAPE_OWNERS:
+    if o not in claimed.values():
+        continue                                     # nothing queries it today; nothing to guard
+    body = read(ROOT / o["file"])
+    for rx in o.get("require", []):
+        check(re.search(rx, body, re.M) is not None,
+              f"{o['file']} no longer matches /{rx}/, which is what makes {o['owner']} scrape. "
+              f"Removing it re-inerts every alert on "
+              f"{o.get('prefixes') or o.get('exact')} — {o['why']}")
+    for rx in o.get("forbid", []):
+        check(re.search(rx, body, re.M) is None,
+              f"{o['file']} matches the FORBIDDEN pattern /{rx}/, which defeats {o['owner']} "
+              f"even though the enablement is still authored. {o['why']}")
+    comp = o.get("companion")
+    if comp:
+        cbody = read(ROOT / comp["file"])
+        check((ROOT / comp["file"]).is_file(),
+              f"{comp['file']} is missing — {comp['why']}")
+        for rx in comp.get("require", []):
+            check(re.search(rx, cbody, re.M) is not None,
+                  f"{comp['file']} no longer matches /{rx}/. The monitor alone is NOT enough here: "
+                  f"{comp['why']}")
+
+# The Longhorn NetworkPolicy must actually grant the path it exists to grant, and no more: the
+# whole point of splitting it out instead of flipping networkPolicies.restrictInternalTraffic off.
+NP = ROOT / "platform/longhorn/networkpolicy-metrics.yaml"
+if any(m.startswith("longhorn_") for m in refs):
+    np = read(NP)
+    check(np != "", f"{NP.relative_to(ROOT)} is missing; the Longhorn scrape is dropped and its "
+                    f"four alerts are inert")
+    check(re.search(r"kind:\s*NetworkPolicy", np) is not None,
+          "platform/longhorn/networkpolicy-metrics.yaml is not a NetworkPolicy")
+    check(re.search(r"app:\s*longhorn-manager", np) is not None,
+          "the Longhorn metrics NetworkPolicy does not select app=longhorn-manager, so it does not "
+          "open the pods that serve /metrics")
+    check(re.search(r"kubernetes\.io/metadata\.name:\s*monitoring", np) is not None,
+          "the Longhorn metrics NetworkPolicy does not admit namespace monitoring, so Prometheus "
+          "still cannot reach longhorn-manager and the storage alerts stay inert")
+    check(re.search(r"port:\s*9500", np) is not None,
+          "the Longhorn metrics NetworkPolicy does not name port 9500 (longhorn-manager's `manager` "
+          "port, which serves /metrics)")
+    # LEAST PRIVILEGE (R-SEC-02): ingress only, one port, and NOT the webhook/recovery ports.
+    check(re.search(r"policyTypes:\s*\n\s*-\s*Ingress\s*$", np, re.M) is not None
+          and "Egress" not in np,
+          "the Longhorn metrics NetworkPolicy is not Ingress-only — it must grant exactly the "
+          "scrape path and nothing else (R-SEC-02)")
+    # Comments are stripped first: the file's header deliberately NAMES 9502/9503 to record that
+    # they stay closed, and a substring search over prose would fail on the documentation of the
+    # very property it is asserting.
+    np_spec = "\n".join(re.sub(r"#.*$", "", ln) for ln in np.splitlines())
+    for closed in ("9502", "9503"):
+        check(closed not in np_spec,
+              f"the Longhorn metrics NetworkPolicy names port {closed} (admission webhook / "
+              f"recovery backend). Only 9500 serves metrics; opening the others to ns monitoring "
+              f"is reach this observability path does not need (R-SEC-02)")
+
+# stale KNOWN_UNWIRED_METRICS entries
+for m in sorted(KNOWN_UNWIRED_METRICS):
+    check(m in refs,
+          f"KNOWN_UNWIRED_METRICS declares `{m}`, which NO alert rule in this repo queries any "
+          f"more — a stale exemption hides the next real gap; delete the entry")
+
+# =============================================================================================
+# (4) up{job="X"} — the axis assertion (1) is structurally blind to.
+#
+# Scoped to files where THIS REPO authors both the Service and the ServiceMonitor (the apps/*
+# ServiceDefinition pattern), because only then is the port name inside the tree. A monitor whose
+# Service comes from a Helm chart cannot be audited statically and is out of scope (header gap).
+# =============================================================================================
+def yaml_docs(path: Path) -> list[dict]:
+    try:
+        return [d for d in yaml.safe_load_all(read(path)) if isinstance(d, dict)]
+    except yaml.YAMLError:
+        return []
+
+
+# job name -> (relpath, monitor endpoint ports, ports the co-authored Services define)
+same_file_monitors: dict[str, tuple[str, set[str], set[str]]] = {}
+for p in sorted(ROOT.rglob("*.yaml")):
+    if any(part.startswith(".") for part in p.relative_to(ROOT).parent.parts):
+        continue
+    txt = read(p)
+    if "kind: ServiceMonitor" not in txt or "kind: Service" not in txt:
+        continue
+    docs = yaml_docs(p)
+    monitors = [d for d in docs if d.get("kind") == "ServiceMonitor"]
+    services = [d for d in docs if d.get("kind") == "Service"]
+    if not monitors or not services:
+        continue
+    svc_ports: set[str] = set()
+    for s in services:
+        for port in (s.get("spec") or {}).get("ports") or []:
+            if isinstance(port, dict) and port.get("name"):
+                svc_ports.add(str(port["name"]))
+    for m in monitors:
+        ep_ports = {str(e["port"]) for e in (m.get("spec") or {}).get("endpoints") or []
+                    if isinstance(e, dict) and e.get("port")}
+        name = (m.get("metadata") or {}).get("name")
+        if name:
+            same_file_monitors[str(name)] = (str(p.relative_to(ROOT)), ep_ports, svc_ports)
+
+for job in sorted(job_refs):
+    sites = ", ".join(sorted(set(job_refs[job])))
+    mon = same_file_monitors.get(job)
+    if mon is None:
+        # No same-file Service+ServiceMonitor pair is named for this job. It may well be produced
+        # by a platform monitor against a chart Service (oauth2-proxy, kubevirt, velero, flux all
+        # are), which this check cannot see — so this is NOT a failure, only unauditable.
+        continue
+    rel, ep_ports, svc_ports = mon
+    missing = sorted(ep_ports - svc_ports)
+    if missing:
+        check(job in KNOWN_UNWIRED_JOBS,
+              f"`up{{job=\"{job}\"}}` ({sites}) can never produce a series: {rel}'s ServiceMonitor "
+              f"scrapes port(s) {missing}, and the Service(s) in that same file define only "
+              f"{sorted(svc_ports) or ['(no named ports)']}. The monitor therefore discovers ZERO "
+              f"targets, there is no `up{{job=\"{job}\"}}` to compare against 0, and the rule is "
+              f"structurally inert — note PrometheusTargetsMissing cannot see this either, because "
+              f"a target that was never discovered has no up series to be 0. Give the Service a "
+              f"named port the workload actually serves metrics on (and an exporter if it has "
+              f"none), or declare it in KNOWN_UNWIRED_JOBS")
+    else:
+        check(job not in KNOWN_UNWIRED_JOBS,
+              f"`{job}` is listed in KNOWN_UNWIRED_JOBS but {rel}'s ServiceMonitor port(s) "
+              f"{sorted(ep_ports)} now all exist on its Service — the register is shrink-only: "
+              f"delete the entry")
+
+# stale KNOWN_UNWIRED_JOBS entries
+for job in sorted(KNOWN_UNWIRED_JOBS):
+    check(job in job_refs,
+          f"KNOWN_UNWIRED_JOBS declares `{job}`, which no alert rule selects via up{{job=...}} any "
+          f"more — a stale exemption hides the next real gap; delete the entry")
+
+# =============================================================================================
+# (5) THE CHECK IS LOAD-BEARING. Asserted against the DECLARATIVE mechanism, in both halves —
+# neither alone is sufficient. The per-test hand-written ci/l0.sh stage is deliberately NOT used
+# (whole-repo-invariants-wired FAILS the gate if one reappears); the property is DECLARED here and
+# HONOURED by ci/l0.sh's --include-scope union.
+# =============================================================================================
+SCOPE_DECL_RE = r"^\s*conformance\.home\.k3s/scope:\s*[\"']?whole-repo"
+SELF = read(ROOT / "conformance" / "tests" / "l0-static" / "alert-metrics-have-scrape-targets"
+            / "chainsaw-test.yaml")
+check(re.search(SCOPE_DECL_RE, SELF, re.M) is not None,
+      "alert-metrics-have-scrape-targets/chainsaw-test.yaml does not declare "
+      "conformance.home.k3s/scope: whole-repo, so the merge gate selects this check only when a "
+      "change happens to touch R-OBS-04. ci/touched-requirements.sh maps apps/* to NOTHING and "
+      "platform/monitoring/* to R-OBS-01/R-OBS-02 — so adding an alert under apps/ or flipping a "
+      "chart's serviceMonitor.enabled back to false would be filtered out of exactly the change "
+      "that re-inerts the alerts")
+L0 = read(ROOT / "ci" / "l0.sh")
+GATE = read(ROOT / "ci" / "gate.sh")
+check("--include-scope" in L0,
+      "ci/l0.sh no longer passes --include-scope to the conformance runner, so the L0 stage is a "
+      "purely requirement-scoped run again and the scope annotation above is inert decoration")
+check(re.search(r"^for s in .*\bl0\b.*; do", GATE, re.M) is not None
+      and re.search(r"fail\).*BLOCK=1", GATE) is not None,
+      "ci/gate.sh does not set the merge block when the l0 stage fails")
+
+# ======================================================================== report
+owners_used = {id(o): o for o in claimed.values()}
+print(f"Alert metric inventory: {n_rules} alerting rule(s) across {len(rule_files)} "
+      f"PrometheusRule file(s) -> {len(refs)} distinct metric name(s)")
+print(f"  claimed by a declared scrape owner: {len(claimed)}/{len(refs) - len(UNIVERSAL & set(refs))}"
+      f"   owners exercised: {len(owners_used)}/{len(SCRAPE_OWNERS)}")
+for o in SCRAPE_OWNERS:
+    ms = sorted(m for m, oo in claimed.items() if oo is o)
+    mark = "  " if ms else "· "
+    print(f"  {mark}{o['file']:<46} {len(ms):>2} metric(s)  {o['owner'][:64]}")
+print(f"\n  DECLARED GAPS (shrink-only registers):")
+print(f"    KNOWN_UNWIRED_METRICS: {len(KNOWN_UNWIRED_METRICS)} — "
+      f"{', '.join(sorted(KNOWN_UNWIRED_METRICS))}")
+print(f"    KNOWN_UNWIRED_JOBS:    {len(KNOWN_UNWIRED_JOBS)} inert up{{job=...}} SLI rule(s) — "
+      f"{', '.join(sorted(KNOWN_UNWIRED_JOBS))}")
+if unowned:
+    print(f"\n  UNCLAIMED (inert, undeclared): {', '.join(unowned)}", file=sys.stderr)
+
+print()
+if not FAILURES:
+    print(f"check OK: alert-metrics-have-scrape-targets — {CHECKS} assertions (R-OBS-04)")
+    raise SystemExit(0)
+print(f"CHECK FAIL (alert-metrics-have-scrape-targets): {len(FAILURES)} failed, "
+      f"{CHECKS - len(FAILURES)} passed", file=sys.stderr)
+for f in FAILURES:
+    print(f"  FAIL {f}", file=sys.stderr)
+raise SystemExit(1)
+PY
@@ -0,0 +1,95 @@
+# =============================================================================
+# L0 STATIC — the alert rules are UNIT-TESTED, by a pinned engine, and the gaps are declared
+# Catalog: docs/14 L0 row ("Pre-apply, in CI") — runs WITHOUT a cluster.
+#
+# R-OBS-04 ("the platform alerts on its own health") is implemented by PrometheusRule CRs, and
+# this repo has shipped both ways they fail SILENTLY:
+#   * PERMANENTLY FIRING — the CNPG primaries alert (fixed 2026-09-12), VPNTunnelDown before it;
+#   * STRUCTURALLY INERT — VeleroNoRecentBackup, whose `time() - <absent series>` yields no
+#     series, so a schedule that had NEVER backed up could not raise it. Prod ran with zero
+#     volume backups and nothing alerted, masked by a resources-only schedule completing
+#     cleanly every night (2026-09-12).
+# An inert rule and a correct rule are indistinguishable while the platform is healthy. Only
+# `promtool test rules` separates them, by constructing the bad state on purpose, offline.
+#
+# The unit tests were then written — and RUN BY NOTHING. promtool was not in the pinned
+# toolchain, no gate stage evaluated the files, and the two harnesses that grew up independently
+# each fetched an engine off the network mid-run if promtool was missing (a GitHub release
+# download in one, a prometheus container image in the other). Coverage that looks present and
+# is enforced nowhere is the failure mode this test ends.
+#
+# GIVEN the repository as authored,
+# WHEN  the ONE rule-unit harness (platform/monitoring/tests/run.sh, which flattens the
+#       COMMITTED PrometheusRule CRs into the rules file promtool wants — never a copy) is run
+#       over every test file in the repo with the PINNED promtool,
+# THEN  promtool is pinned in BOTH versions.env files in lockstep at the Prometheus version prod
+#       actually runs, baked into the image and installed on the CI runner; the promtool in use
+#       reports exactly that version; no harness acquires an engine at run time; there is
+#       exactly ONE harness; every rule-unit test file PASSES; the harness is proven able to
+#       FAIL by a mutated synthetic test on every run; and every alert rule with NO unit test is
+#       ENUMERATED in a shrink-only register, so the gap is reported rather than hidden.
+#
+# MISSING TESTS: RATCHET, NOT SKIP, NOT BLANKET-FAIL. 48 of 55 alert rules have no unit test
+# today. Failing on all of them would make the gate red until ~48 tests exist (so it would be
+# disabled, and a disabled gate protects nothing); merely reporting is precisely how the CNPG
+# tests came to be enforced by nothing. So the gap is DECLARED in check.sh, printed with counts
+# every run, and CANNOT GROW: a new PrometheusRule, or a new alert in an already-tested file,
+# FAILS without a test, and a stale register entry FAILS too. A missing test is never an exit-3
+# skip — "SKIPPED is not green" is preserved for the one thing that is genuinely an environment
+# gap: promtool being absent.
+#
+# STATUS: EXECUTABLE. `check.sh` is an offline assertion script (standard library + the harness
+# it delegates to); conformance/run.sh --layer l0 and ci/l0.sh run it directly, and this
+# Chainsaw Test wraps the SAME script.
+#
+# NOT proven (named in check.sh's header): that an alert reaches a human (Alertmanager routing
+# and SMTP are L3 / R-OBS-02), that a threshold is the right one, that a rule file is actually
+# reconciled into a cluster, or that an author's assertions are meaningful — coverage of one
+# alert is detected by its name appearing in a covering test file, and only the mutation
+# self-test proves the harness CAN fail. R-OBS-04 is tagged for the static slice only: the rules
+# the repo ships behave, under the engine prod runs, as their own unit tests say.
+# =============================================================================
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: alert-rules-unit-tested
+  labels:
+    conformance.home.k3s/R-OBS-04: "true"
+    conformance.home.k3s/R-TEST-02: "true"
+  annotations:
+    conformance.home.k3s/requirements: "R-OBS-04, R-TEST-02"
+    conformance.home.k3s/layer: "L0"
+    # WHOLE-REPO SCOPE — this invariant quantifies over every PrometheusRule in the tree
+    # (apps/wave-0..2, platform/cnpg, platform/kubevirt, platform/monitoring), and the register
+    # it maintains is a property of the WHOLE repo, not of any one path.
+    #
+    # WHY IT MUST NOT BE REQUIREMENT-SCOPED: ci/touched-requirements.sh's coarse path map keys
+    # apps/* to NOTHING and platform/monitoring/* to R-OBS-01/02 — not R-OBS-04. So adding a new
+    # untested PrometheusRule under apps/, or editing one under platform/kubevirt/, attributes
+    # no requirement this test carries, and a requirement-scoped selection would filter the
+    # check out of exactly the change that adds the untested alert. The same blind spot that let
+    # `prod-baremetal-not-dev-surface` be filtered out of the run that gated its own breakage
+    # (DECISIONS-LOG 2026-09-12).
+    #
+    # Declaring the scope also makes an honest SKIP loud: lib/run_l1_offline.py turns a rc-3
+    # skip of a scope-declaring check into the runner's rc 3, and ci/l0.sh into the gate's rc 3.
+    # So a gate run on a toolchain WITHOUT promtool reports UNWIRED instead of green — which is
+    # the whole reason this check exists rather than another hand-written ci/l0.sh stage.
+    conformance.home.k3s/scope: "whole-repo"
+    conformance.home.k3s/safety-critical: "false"
+    conformance.home.k3s/executable: "true"
+    conformance.home.k3s/intent: >-
+      Every committed alert rule that has unit tests passes them under the pinned promtool that
+      matches prod's Prometheus, exactly one harness runs them, nothing fetches a rule engine at
+      run time, the harness is proven able to fail, and every alert rule without a unit test is
+      enumerated in a register that can only shrink.
+spec:
+  steps:
+    - name: run-every-alert-rule-unit-test-and-report-the-gaps
+      description: >-
+        Assert the promtool pin is in lockstep and baked, run the single rule-unit harness over
+        every test file in the repo, prove it can fail via a mutated synthetic test, and
+        enumerate every PrometheusRule with no unit tests against the shrink-only register.
+      try:
+        - script:
+            content: bash ./check.sh
@@ -0,0 +1,580 @@
+#!/usr/bin/env bash
+# =============================================================================
+# L0 static check (offline, no cluster) — alert-rules-unit-tested
+# Serves: R-OBS-04 ("Platform alerts on its own health (nodes, storage, GitOps, certs,
+#                    VPN)." — spec docs/10-observability-and-alerting.md)
+#         R-TEST-02 ("Tests are reproducible: deterministic, hermetic, single-command."
+#                    — spec docs/14-testing-and-conformance.md)
+#
+# WHY THIS EXISTS — AN UNTESTED ALERT IS NOT A MONITORING CONTROL
+# --------------------------------------------------------------
+# This repo has shipped BOTH halves of the alerting failure space to prod:
+#   * a PERMANENTLY-FIRING `critical` (the CNPG alert fixed 2026-09-12; VPNTunnelDown before
+#     it), and
+#   * a STRUCTURALLY INERT rule — VeleroNoRecentBackup, whose `time() - <absent series>`
+#     yields no series, so a schedule that had NEVER backed up could not raise it. Prod ran
+#     with no volume backups at all and nothing alerted (2026-09-12).
+# Neither is visible from the expression, from `kubectl apply`, or from a healthy cluster: an
+# inert rule and a correct rule are indistinguishable while everything is fine. `promtool test
+# rules` is the only tool that separates them, because the BAD state can be constructed on
+# purpose. Unit tests for those rules were then WRITTEN — and evaluated by nothing: promtool
+# was not in the pinned toolchain, no gate stage ran the files, and each of the two harnesses
+# that existed acquired an engine off the network mid-run if one was missing. Coverage that
+# looks present and is never enforced is the failure mode this check ends.
+#
+# GIVEN the repository as authored,
+# WHEN  the ONE rule-unit harness (platform/monitoring/tests/run.sh, which flattens the
+#       COMMITTED PrometheusRule CRs — never a copy) is asked which manifests are under test
+#       and then run over every test file in the repo,
+# THEN  (1) promtool is a PINNED member of the toolchain: PROMTOOL_VERSION is declared in BOTH
+#           infra/devcontainer/versions.env and ci/versions.env and the two AGREE (the repo's
+#           lockstep rule), the Containerfile takes it as a build ARG, installs it from the
+#           pinned prometheus release and records it for provenance, dev.sh passes it, and the
+#           CI runner installs it for the l0 stage;
+#       (2) the promtool ACTUALLY IN USE reports exactly that pinned version — a unit test is
+#           evidence only if the engine matches the one prod evaluates rules with;
+#       (3) NO harness acquires a rule engine at RUN TIME — neither `curl | tar -xz` of a
+#           GitHub release nor a `podman/docker run` of a prometheus image. Both existed on
+#           2026-09-12 and both are removed; this is the regression guard;
+#       (4) there is exactly ONE harness. Two were written independently within an hour of
+#           each other; the one nothing runs is the one that rots;
+#       (5) every rule-unit test file in the repo PASSES, run through that harness (which
+#           `promtool check rules` first, so a non-parsing rules file cannot make unit tests
+#           pass vacuously by finding no rules at all);
+#       (6) the harness is NOT VACUOUS: a synthetic PrometheusRule + companion test is run
+#           through the SAME harness twice — intact (must PASS) and with one expectation
+#           mutated (must FAIL) — so a harness that has silently stopped evaluating anything
+#           is caught on every run, not only when someone thinks to try it;
+#   AND (7) the alert rules with NO unit tests are ENUMERATED and RATCHETED: each is declared
+#           below, printed with counts on every run, and the register can only SHRINK.
+#
+# WHY A MISSING TEST IS A RATCHET AND NOT AN OUTRIGHT FAIL (the decision, and its reasons)
+# ---------------------------------------------------------------------------------------
+# 48 of the repo's 55 alert rules have no unit test today. Three options were on the table:
+#   * FAIL on any missing test — correct in principle, but it makes the merge gate red for
+#     every change until ~48 unit tests exist, so in practice the gate gets disabled, and a
+#     disabled gate protects nothing.
+#   * merely REPORT — the gap prints and nothing holds it. That is exactly how the CNPG unit
+#     tests came to exist and be enforced by nothing; "it is in the output somewhere" is not
+#     enforcement.
+#   * RATCHET (chosen) — the gap is DECLARED IN THE REPO as a reviewable register, printed with
+#     counts on every gate run, and it CANNOT GROW: a new PrometheusRule, or a new alert in a
+#     file that already has tests, FAILS unless it ships a unit test. Removing an entry requires
+#     writing the test, and a STALE entry (file gone, or now covered) also FAILS, so the
+#     register cannot rot into fiction.
+# "SKIPPED is not green" is honoured: a missing test is NEVER an exit-3 skip here. This check
+# exits 0 only with the gap fully enumerated, and exits 1 the moment the debt grows, the
+# register drifts, or a test that exists stops passing.
+# The one exit-3 path is promtool itself being ABSENT — an environment gap, not a code property
+# (the same convention as ci/l0.sh's kyverno handling), and this test DECLARES
+# `conformance.home.k3s/scope: whole-repo`, which makes lib/run_l1_offline.py turn that skip
+# into the runner's rc 3 and ci/l0.sh into the gate's rc 3: UNWIRED, never green. promtool
+# PRESENT AT THE WRONG VERSION is a FAILURE, not a skip: that case still prints SUCCESS while
+# evaluating the rules with an engine prod does not run.
+#
+# WHAT THIS DOES *NOT* PROVE (honest gaps):
+#   - It does not prove an alert reaches a human. promtool evaluates rules against synthetic
+#     series in-process; Alertmanager routing, SMTP delivery and inhibition are L3
+#     (tests/l3-fault-injection/alerting) and R-OBS-02, and are not claimed here.
+#   - It does not prove the THRESHOLDS are right, only that a rule behaves as its own unit
+#     test says.
+#   - It does not prove a rule file is RECONCILED into a cluster. An alert file no
+#     kustomization includes is a separate "looks applied and isn't" failure, not audited here.
+#   - Coverage of an individual alert is detected by its NAME appearing in a test file that
+#     covers its manifest. A test file that merely mentions a name without asserting anything
+#     counts as covered; only the mutation self-test (6) proves the harness CAN fail, not that
+#     every author wrote a meaningful assertion. Review still owns test quality.
+#   - It does not read the live cluster, so "the pin matches prod's Prometheus" is asserted
+#     against the repo's pin, which was established by a live read recorded in
+#     infra/devcontainer/versions.env (2026-09-12: v3.14.0-distroless).
+# =============================================================================
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "${DIR}/../../../.." && pwd)"        # repo root
+PYTHON="${PYTHON:-python3}"
+HARNESS="${ALERT_RULE_HARNESS:-${ROOT}/platform/monitoring/tests/run.sh}"
+
+# Honest SKIP (never green) if the thing under test is not present at all. Because this test
+# declares scope: whole-repo, the runner turns this into rc 3 for the whole L0 stage — a
+# PrometheusRule-less repo is a vanished tree, not a pass.
+if ! grep -rqls --include='*.yaml' -e '^[[:space:]]*kind:[[:space:]]*PrometheusRule[[:space:]]*$' \
+       "${ROOT}/platform" "${ROOT}/apps" 2>/dev/null; then
+  echo "check SKIPPED: no PrometheusRule under platform/ or apps/ — nothing to test" >&2
+  exit 3
+fi
+
+# promtool resolution. PROMTOOL= overrides (the same override the harness honours); otherwise
+# PATH. Absent -> every OFFLINE assertion still runs and the check exits 3, so a toolchain gap
+# is reported as a gap and never as a pass.
+PROMTOOL_BIN="${PROMTOOL:-$(command -v promtool || true)}"
+if [ -n "${PROMTOOL_BIN}" ] && [ -x "${PROMTOOL_BIN}" ]; then
+  PROMTOOL_BIN="$(cd "$(dirname "${PROMTOOL_BIN}")" && pwd)/$(basename "${PROMTOOL_BIN}")"
+else
+  PROMTOOL_BIN=""
+fi
+
+cd "${ROOT}"
+"${PYTHON}" - "${ROOT}" "${HARNESS}" "${PROMTOOL_BIN}" <<'PY'
+"""Assert the alert-rule unit tests are pinned, enforced, non-vacuous, and that the alert
+rules with no tests are enumerated and ratcheted. Standard library + the harness itself."""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections import defaultdict
+from pathlib import Path
+
+ROOT = Path(sys.argv[1])
+HARNESS = Path(sys.argv[2])
+PROMTOOL = sys.argv[3]
+sys.dont_write_bytecode = True          # keep __pycache__ out of the tracked tree
+
+FAILURES: list[str] = []
+CHECKS = 0
+
+
+def check(cond, msg):
+    global CHECKS
+    CHECKS += 1
+    if not cond:
+        FAILURES.append(msg)
+
+
+# =============================================================================
+# THE DECLARED REGISTER (assertion 7). Shrink-only; see the header for why this is a ratchet.
+#
+# UNTESTED_FILES — PrometheusRule files no test file covers AT ALL. A file listed here that later
+# gains coverage, or stops carrying a PrometheusRule, FAILS as stale.
+#
+# THE TWELVE apps/* ENTRIES ARE GONE (2026-09-13). They were the single `<app>-down` liveness rules
+# generated from one ServiceDefinition template, and the register's description of them as one
+# template was exactly why leaving them untested was so expensive: ONE wrong expression was wrong
+# twelve times, and it was — `up{job="<app>"} == 0` against a job no scrape target produced, inert on
+# prod for all twelve. They are now covered by apps/wave-0/tests/app-slis.test.yaml,
+# apps/wave-1/tests/app-slis.test.yaml and apps/wave-2/tests/app-slis.test.yaml, each rule pinned
+# BOTH ways (quiet on the healthy state, firing on no-ready-replica, and firing when the signal
+# VANISHES — the failure mode that produced the class). platform/kubevirt/alerts.yaml (4 rules) is
+# now the only entry left and is where the next tests belong.
+# =============================================================================
+UNTESTED_FILES = {
+    "platform/kubevirt/alerts.yaml",
+}
+
+# UNTESTED_ALERTS — individual alerts inside a file that IS covered by a test file, but whose
+# own rule nothing asserts on. This is the half that stops a new alert being slipped into an
+# already-"tested" file untested: anything not listed here must appear in a covering test.
+# The monitoring block is large because backups.test.yaml (the repo's first suite) deliberately
+# covers the Velero/backup rules only. It SHRANK by seven on 2026-09-13, when
+# platform/monitoring/tests/longhorn.test.yaml took on the whole platform-health.longhorn group
+# plus the three kubelet-based PVC-fill rules it has to be measured against (the per-volume
+# Longhorn "capacity" rule was deleted as a permanently-firing duplicate of them, so proving the
+# redundancy meant asserting on the rules that survive). Only
+# PersistentVolumeFillingUpPredicted is still unasserted in pvc-capacity-alerts.yaml.
+# It SHRANK BY TWO MORE on 2026-09-14: platform/monitoring/tests/node-io-cause.test.yaml pins the
+# eight new platform-health.node-io-cause rules, and its healthy fixture asserts NodeIOPressureHigh
+# and NodeIOPressureCritical quiet on the same measured state — the whole point of that fixture is
+# that the two PSI detectors and the eight cause rules must agree about what "healthy" is, so the
+# detectors are no longer unasserted.
+# It SHRANK BY ONE on 2026-09-19: platform/monitoring/tests/vpn-egress.test.yaml pins the two new
+# egress-steering rules, and asserts VPNTunnelDown QUIET in all four fixtures — that silence IS the
+# claim those rules exist for (tun0 up and passing traffic while vpn-class egress is dropped), so it
+# had to become an assertion rather than a sentence in a comment.
+UNTESTED_ALERTS = {
+    ("platform/cnpg/alerts.yaml", "CNPGWALArchiveBacklog"),
+    ("platform/cnpg/alerts.yaml", "CNPGNoRecoverabilityPoint"),
+    ("platform/cnpg/alerts.yaml", "CNPGNoRecentBaseBackup"),
+    ("platform/cnpg/alerts.yaml", "CNPGWALVolumeNotRecycling"),
+    ("platform/cnpg/alerts.yaml", "CNPGMetricsCollectorErroring"),
+    ("platform/monitoring/alerts.yaml", "NodeExporterDown"),
+    ("platform/monitoring/alerts.yaml", "NodeMemoryPressureHigh"),
+    ("platform/monitoring/alerts.yaml", "NodeDiskFillingUp"),
+    ("platform/monitoring/alerts.yaml", "NodeCPUPressureHigh"),
+    ("platform/monitoring/alerts.yaml", "NodeCPULoadHigh"),
+    ("platform/monitoring/alerts.yaml", "FluxReconciliationFailure"),
+    ("platform/monitoring/alerts.yaml", "FluxResourceSuspended"),
+    ("platform/monitoring/alerts.yaml", "CertificateExpiringSoon"),
+    ("platform/monitoring/alerts.yaml", "CertificateExpiryImminent"),
+    ("platform/monitoring/alerts.yaml", "CertificateNotReady"),
+    ("platform/monitoring/alerts.yaml", "HubbleDeniedFlowSpike"),
+    ("platform/monitoring/alerts.yaml", "KeycloakDown"),
+    ("platform/monitoring/alerts.yaml", "KeycloakDatabaseDown"),
+    ("platform/monitoring/alerts.yaml", "KeycloakClientSecretReconcilerFailing"),
+    ("platform/monitoring/alerts.yaml", "KeycloakClientSecretReconcilerStale"),
+    ("platform/monitoring/alerts.yaml", "PrometheusTargetsMissing"),
+    ("platform/monitoring/alerts.yaml", "ImageUpdateAutomationFailing"),
+    ("platform/monitoring/alerts.yaml", "ImagePolicyStalled"),
+    ("platform/monitoring/alerts.yaml", "UpdateHealthGateFailed"),
+    ("platform/monitoring/pvc-capacity-alerts.yaml", "PersistentVolumeFillingUpPredicted"),
+}
+
+# --------------------------------------------------------------- (1) the pins, in lockstep
+def env_pin(rel: str, key: str) -> str | None:
+    f = ROOT / rel
+    if not f.is_file():
+        return None
+    m = re.search(rf'^{re.escape(key)}=["\']?([^"\'\s#]+)', f.read_text(), re.M)
+    return m.group(1) if m else None
+
+
+DEV_PIN = env_pin("infra/devcontainer/versions.env", "PROMTOOL_VERSION")
+CI_PIN = env_pin("ci/versions.env", "PROMTOOL_VERSION")
+check(DEV_PIN is not None,
+      "infra/devcontainer/versions.env declares no PROMTOOL_VERSION — promtool is not part of the "
+      "baked toolchain, so the alert unit tests are evaluated by whatever the host happens to "
+      "have, or by nothing at all (which is where this repo was on 2026-09-12)")
+check(CI_PIN is not None,
+      "ci/versions.env declares no PROMTOOL_VERSION — the gate's own version file does not pin the "
+      "rule engine, so CI and the devcontainer can silently diverge")
+check(DEV_PIN is None or DEV_PIN == CI_PIN,
+      f"PROMTOOL_VERSION is NOT in lockstep: infra/devcontainer/versions.env={DEV_PIN!r} vs "
+      f"ci/versions.env={CI_PIN!r}. The repo's rule is that the conformance-tool versions in the "
+      f"two files stay identical, so a laptop and CI run the same engine")
+
+CF = ROOT / "infra/devcontainer/Containerfile"
+cf_text = CF.read_text() if CF.is_file() else ""
+check(re.search(r"^ARG PROMTOOL_VERSION\s*$", cf_text, re.M),
+      "infra/devcontainer/Containerfile has no `ARG PROMTOOL_VERSION` — the pin is declared but "
+      "the image build does not consume it")
+check("prometheus/prometheus/releases/download" in cf_text and "promtool" in cf_text,
+      "infra/devcontainer/Containerfile does not install promtool from the pinned prometheus "
+      "release tarball (promtool ships inside it)")
+check('echo "promtool=${PROMTOOL_VERSION}"' in cf_text,
+      "infra/devcontainer/Containerfile does not record promtool in /etc/dev-toolchain-versions — "
+      "that provenance line is how an operator tells a stale image from a current one")
+
+DEVSH = ROOT / "infra/devcontainer/dev.sh"
+check(DEVSH.is_file() and "--build-arg PROMTOOL_VERSION=" in DEVSH.read_text(),
+      "infra/devcontainer/dev.sh does not pass --build-arg PROMTOOL_VERSION — the ARG would be "
+      "empty and the build would fetch a bogus URL")
+
+INSTALL = ROOT / ".gitea/workflows/scripts/install-tools.sh"
+if INSTALL.is_file():
+    itext = INSTALL.read_text()
+    check("PROMTOOL_VERSION" in itext
+          and re.search(r"^\s*l0\)[^\n]*install_promtool", itext, re.M),
+          ".gitea/workflows/scripts/install-tools.sh does not install promtool for the l0 stage — "
+          "on the CI runner this check would exit 3 (UNWIRED) forever and the alert unit tests "
+          "would be enforced nowhere, which is the exact gap it exists to close")
+
+# --------------------------------------------- (3)(4) one harness, and it fetches no engine
+check(HARNESS.is_file() and os.access(HARNESS, os.X_OK),
+      f"the rule-unit harness is missing or not executable at {HARNESS.relative_to(ROOT)} — "
+      f"nothing would run the alert unit tests")
+
+# Any script that invokes `promtool test rules` is a rule-unit harness. There must be exactly
+# one: two harnesses were written independently on 2026-09-12 (a cnpg-only script and this one),
+# and the one nothing runs is the one that rots out of sync with the rules.
+harnesses: list[str] = []
+fetchers: list[str] = []
+FETCH_RE = re.compile(
+    r"(curl|wget)[^\n]*prometheus/prometheus/releases"          # GitHub release download
+    r"|(podman|docker)\s+run[^\n]*prometheus",                  # container-image pull
+    re.I)
+# Two exclusions, both the repo's existing "reference, not declaration" rule (see
+# ci/touched-requirements.sh changed_diff() rules 2-3):
+#   * THIS CHECK'S OWN DIRECTORY. It names every forbidden pattern in order to forbid it, so
+#     scanning itself would make both guards permanently red — the self-referential trap.
+#   * THE PINNED TOOLCHAIN INSTALLERS. Downloading the pinned promtool is their JOB, at a
+#     reviewed seam (an image build, or the runner's tool-install step), from a version in
+#     versions.env. What is forbidden is a RULE-UNIT RUN acquiring its own engine: then the
+#     version, the network and the machine are decided silently at test time, and a missing
+#     toolchain becomes a green run instead of an exit 3.
+# NESTED WORKTREES: skip dot-DIRECTORIES (.git, .claude) while still matching dot-FILES such
+# as .sops.yaml. .claude/worktrees/agent-*/ holds full repo copies for isolated agent runs, so
+# a bare rglob from ROOT audited up to 18 duplicates of every file — which both invents FAILs
+# and, worse, can satisfy an "something declares X" check from a copy rather than real source.
+# Same fix as egress-paths-selected-by-rules. .claude/ is gitignored (.gitignore:43).
+SELF_DIR = "conformance/tests/l0-static/alert-rules-unit-tested/"
+INSTALLERS = (".gitea/workflows/scripts/install-tools.sh", "infra/devcontainer/")
+for p in sorted(ROOT.rglob("*.sh")):
+    rel = str(p.relative_to(ROOT))
+    if rel.startswith((".git/", ".claude/", "conformance/runs/", SELF_DIR)):
+        continue
+    try:
+        text = p.read_text()
+    except (OSError, UnicodeDecodeError):
+        continue
+    body = "\n".join(l for l in text.splitlines() if not l.lstrip().startswith("#"))
+    if "promtool" in body and re.search(r"test\s+rules", body):
+        harnesses.append(rel)
+    if FETCH_RE.search(body) and not rel.startswith(INSTALLERS):
+        fetchers.append(rel)
+
+check(harnesses == [str(HARNESS.relative_to(ROOT))],
+      f"expected exactly ONE rule-unit harness ({HARNESS.relative_to(ROOT)}) but found "
+      f"{harnesses}. A second harness means two behaviours and two things to keep in step; the "
+      f"one the gate does not run is the one that rots. Fold it in instead")
+check(not fetchers,
+      f"{fetchers} acquire a rule ENGINE at run time (a prometheus release download or a "
+      f"prometheus container image). promtool must come from the pinned toolchain "
+      f"(PROMTOOL_VERSION): a run-time fetch decides the version, the network and the machine "
+      f"silently at test time, makes the tests non-hermetic (R-TEST-02), and quietly turns 'the "
+      f"toolchain has no promtool' into a green run — which is how it stayed missing")
+
+# ------------------------------------------------------------------ discover the alert files
+# Alert files: tracked YAML carrying a PrometheusRule. conformance/ is excluded deliberately —
+# the PrometheusRules under tests/l1-rendering/*/golden/ are EXPECTED-RENDER fixtures for the
+# render checks, not rules any cluster evaluates. Everything a cluster actually gets lives under
+# apps/, platform/, platform-config/ or clusters/.
+def tracked_yaml() -> list[Path]:
+    out = subprocess.run(["git", "-C", str(ROOT), "ls-files", "-z", "*.yaml", "*.yml"],
+                         capture_output=True, text=True)
+    if out.returncode == 0 and out.stdout:
+        return [ROOT / p for p in out.stdout.split("\0") if p]
+    # No usable index (the gate container mounts a worktree whose .git points outside the
+    # mount). Fall back to a filesystem walk rather than auditing nothing.
+    return sorted(p for p in ROOT.rglob("*.y*ml") if not any(part.startswith(".") for part in p.relative_to(ROOT).parent.parts))
+
+
+KIND_RE = re.compile(r"^\s*kind:\s*PrometheusRule\s*$", re.M)
+ALERT_RE = re.compile(r"^\s*-\s*alert:\s*(\S+)", re.M)
+
+alert_files: dict[str, list[str]] = {}
+for p in tracked_yaml():
+    rel = str(p.relative_to(ROOT))
+    if rel.startswith("conformance/") or not p.is_file():
+        continue
+    try:
+        text = p.read_text()
+    except (OSError, UnicodeDecodeError):
+        continue
+    if KIND_RE.search(text):
+        alert_files[rel] = ALERT_RE.findall(text)
+
+check(len(alert_files) > 0,
+      "no PrometheusRule found outside conformance/ — discovery or the repo layout changed, and "
+      "this check would silently audit nothing")
+
+# ------------------- ask the HARNESS which manifests are under test (never re-derive it here)
+# Two implementations of "which rules does this test cover" would eventually disagree, and the
+# disagreement shows up as a file the gate believes is tested and the harness never touches.
+listing = subprocess.run(["bash", str(HARNESS), "--list"], capture_output=True, text=True,
+                         cwd=str(ROOT))
+check(listing.returncode == 0,
+      f"`{HARNESS.relative_to(ROOT)} --list` failed (rc={listing.returncode}): "
+      f"{(listing.stderr or listing.stdout).strip()[-600:]}")
+covering: dict[str, list[str]] = defaultdict(list)   # manifest -> [test files]
+for line in listing.stdout.splitlines():
+    if "\t" in line:
+        tfile, manifest = line.split("\t", 1)
+        covering[manifest.strip()].append(tfile.strip())
+
+for manifest in sorted(covering):
+    check(manifest in alert_files,
+          f"the harness reports {manifest} as under test, but it is not one of the "
+          f"PrometheusRule files found in the repo — the mapping and the tree disagree")
+
+# --------------------------------------------------------- (2) the engine is the pinned one
+version_line = ""
+if PROMTOOL:
+    vp = subprocess.run([PROMTOOL, "--version"], capture_output=True, text=True)
+    out = (vp.stdout + vp.stderr).strip()
+    version_line = out.splitlines()[0] if out else ""
+    m = re.search(r"version\s+(\d+\.\d+\.\d+)", version_line)
+    found = m.group(1) if m else None
+    check(found is not None,
+          f"could not parse a version from `promtool --version`: {version_line!r}")
+    check(found is None or DEV_PIN is None or found == DEV_PIN,
+          f"promtool reports {found}, but the toolchain pins PROMTOOL_VERSION={DEV_PIN} (the "
+          f"Prometheus version prod runs). promtool IS the rule engine: a unit test green under "
+          f"one version and red under another is worse than no test. Run the gate in the pinned "
+          f"devcontainer (rebuild it: ./infra/devcontainer/dev.sh build), or set PROMTOOL= to a "
+          f"v{DEV_PIN} binary. A FAILURE, not a skip, because the wrong engine still prints "
+          f"SUCCESS")
+
+# ------------------------------------------------- (5) every rule-unit test file must pass
+if PROMTOOL:
+    env = dict(os.environ, PROMTOOL=PROMTOOL)
+    run = subprocess.run(["bash", str(HARNESS)], capture_output=True, text=True,
+                         cwd=str(ROOT), env=env)
+    tailed = "\n        ".join((run.stdout + run.stderr).strip().splitlines()[-40:])
+    check(run.returncode == 0,
+          f"`{HARNESS.relative_to(ROOT)}` FAILED (rc={run.returncode}) — the committed alert "
+          f"rules do not behave as their own unit tests say:\n        {tailed}")
+
+    # ------------------------------------------- (6) the harness is proven non-vacuous
+    # A synthetic PrometheusRule + companion test through the SAME harness, outside the repo so
+    # discovery never picks it up. Intact must PASS; a mutated expectation must FAIL. Without
+    # this, a harness that stopped evaluating anything (an empty extraction, a rule file written
+    # under the wrong name) would report green forever — which is the disease being treated.
+    work = tempfile.mkdtemp(prefix="alert-rules-selftest.")
+    try:
+        (Path(work) / "synth.yaml").write_text("""apiVersion: monitoring.coreos.com/v1
+kind: PrometheusRule
+metadata:
+  name: selftest
+spec:
+  groups:
+    - name: selftest
+      rules:
+        - alert: SelfTestCanary
+          expr: selftest_metric > 0
+          for: 5m
+          annotations:
+            runbook_url: https://${BASE_DOMAIN}/runbooks/selftest
+""")
+        test_yaml = """rule_files:
+  - generated.rules.yaml
+evaluation_interval: 1m
+tests:
+  - interval: 1m
+    name: canary fires only after `for` elapses
+    input_series:
+      - series: 'selftest_metric'
+        values: '1x10'
+    promql_expr_test:
+      - expr: 'ALERTS{alertname="SelfTestCanary",alertstate="firing"}'
+        eval_time: EVAL_TIME
+        exp_samples:
+          - labels: 'ALERTS{alertname="SelfTestCanary",alertstate="firing"}'
+            value: 1
+"""
+        synth_test = Path(work) / "synth.promtool-test.yaml"
+        synth_test.write_text(test_yaml.replace("EVAL_TIME", "6m"))
+        good = subprocess.run(["bash", str(HARNESS), str(synth_test)],
+                              capture_output=True, text=True, cwd=str(ROOT), env=env)
+        check(good.returncode == 0,
+              "self-test: the INTACT synthetic unit test did not pass, so the harness itself is "
+              "broken and every green result above is meaningless:\n        "
+              + "\n        ".join((good.stdout + good.stderr).strip().splitlines()[-20:]))
+        # Mutation: assert firing at 2m, which `for: 5m` forbids.
+        synth_test.write_text(test_yaml.replace("EVAL_TIME", "2m"))
+        bad = subprocess.run(["bash", str(HARNESS), str(synth_test)],
+                             capture_output=True, text=True, cwd=str(ROOT), env=env)
+        check(bad.returncode != 0,
+              "self-test: a MUTATED expectation (firing before `for:` elapsed) still PASSED — "
+              "the harness is not actually evaluating anything, so every green result above is "
+              "vacuous")
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+# --------------------------------------------------------- (7) the gap inventory + ratchet
+INVENTORY: list[str] = []
+GAP_FILES: list[str] = []
+alerts_total = covered_total = 0
+
+for rel in sorted(alert_files):
+    names = alert_files[rel]
+    alerts_total += len(names)
+    check(len(names) > 0,
+          f"{rel} declares a PrometheusRule but no `alert:` rule was parsed out of it — the "
+          f"parser or the file shape changed, and any unit test over it would pass vacuously")
+    tests = covering.get(rel, [])
+    if not tests:
+        GAP_FILES.append(rel)
+        INVENTORY.append(f"  {rel:<46} alerts={len(names):<3} tested=0/{len(names):<3} NO TEST FILE")
+        check(rel in UNTESTED_FILES,
+              f"{rel} carries {len(names)} alert rule(s) and NO test file covers it. A new "
+              f"PrometheusRule must ship promtool unit tests: this repo has shipped both a "
+              f"permanently-firing critical and a structurally inert alert, and neither was "
+              f"visible without them. Add `{rel[:-5]}.promtool-test.yaml` (companion convention) "
+              f"or a <component>/tests/*.test.yaml suite. If this is deliberate debt it must be "
+              f"DECLARED in UNTESTED_FILES in this check — the register is what keeps the gap "
+              f"visible instead of silent")
+        continue
+
+    check(rel not in UNTESTED_FILES,
+          f"{rel} is listed in UNTESTED_FILES but is now covered by {tests} — the register is "
+          f"shrink-only: delete the line so the next missing test is caught")
+    text = "".join((ROOT / t).read_text() for t in tests if (ROOT / t).is_file())
+    # "COVERED" MUST MEAN ASSERTED, NOT MENTIONED (tightened 2026-09-19).
+    # This used to be a bare word match over the whole test file, so an alert named anywhere —
+    # including in a PROSE COMMENT — counted as tested. Hit for real while adding
+    # platform/monitoring/tests/vpn-egress.test.yaml: its header comment explains that VPNTunnelDown
+    # stays quiet during an egress-steering failure, and that sentence alone was enough to make this
+    # check declare VPNTunnelDown "asserted on" and demand its removal from UNTESTED_ALERTS. Deleting
+    # the register entry would then have recorded coverage that did not exist — the exact "looks fixed"
+    # outcome this check exists to prevent, produced BY the check.
+    # Now an alert counts only when a test file names it in an `alertname:` position, with comment
+    # lines stripped first so a commented-out assertion does not count either.
+    # MEASURED BLAST RADIUS BEFORE TIGHTENING: of 61 alerts across the PrometheusRule manifests, 32 are
+    # asserted in one of the two idioms below, 29 are not mentioned at all (already declared in the
+    # registers), and ZERO are prose-only — so this change failed nothing on the day it landed. That
+    # mattered because the registers are shrink-only: had any alert been prose-only, tightening would
+    # have needed a register entry it is not allowed to add. (The first measurement said 31/30/0 because
+    # it scanned only tests/*.test.yaml and missed the <manifest>.promtool-test.yaml companions.)
+    text_no_comments = "\n".join(
+        l for l in text.split("\n") if not l.lstrip().startswith("#")
+    )
+    # BOTH promtool idioms count, because both are real assertions:
+    #   alert_rule_test:   - alertname: CNPGPrimariesCoLocated
+    #   promql_expr_test:  - expr: 'ALERTS{alertname="CNPGPrimariesCoLocated"}'
+    # Matching only the first produced a FALSE NEGATIVE on CNPGPrimariesCoLocated, which
+    # platform/cnpg/alerts.promtool-test.yaml pins across FOUR scenarios entirely through the second
+    # form. Had that been believed, the "fix" would have been a redundant duplicate test for an alert
+    # already better covered than most.
+    covered = [n for n in names
+               if re.search(rf'(?:alertname:\s*|alertname="){re.escape(n)}\b', text_no_comments)]
+    covered_total += len(covered)
+    for n in names:
+        if n in covered:
+            check((rel, n) not in UNTESTED_ALERTS,
+                  f"{rel}: alert {n} is listed in UNTESTED_ALERTS but IS asserted on now — "
+                  f"remove the stale entry (the register is shrink-only)")
+        else:
+            check((rel, n) in UNTESTED_ALERTS,
+                  f"{rel}: alert {n} has NO unit test in {tests}. This file is already covered, "
+                  f"so a new alert in it must be tested too — otherwise a 'tested' alert file "
+                  f"quietly grows untested rules")
+    INVENTORY.append(f"  {rel:<46} alerts={len(names):<3} tested={len(covered)}/{len(names):<3} "
+                     f"{','.join(tests)}")
+
+# stale register entries
+for rel in sorted(UNTESTED_FILES - set(alert_files)):
+    check(False, f"UNTESTED_FILES lists {rel}, which carries no PrometheusRule in this repo any "
+                 f"more — a stale exemption hides the next real gap; delete the line")
+for rel in sorted({f for f, _ in UNTESTED_ALERTS} - set(alert_files)):
+    check(False, f"UNTESTED_ALERTS lists alerts in {rel}, which carries no PrometheusRule in this "
+                 f"repo any more — delete those lines")
+
+# --------------------------------------------------------------------------------- report
+print("Alert-rule unit-test inventory (PrometheusRule -> covering test file(s)):")
+for line in INVENTORY:
+    print(line)
+print(f"\nharness: {HARNESS.relative_to(ROOT)}   promtool: {version_line or 'NOT FOUND'}")
+print(f"pinned:  PROMTOOL_VERSION={DEV_PIN} (devcontainer) / {CI_PIN} (ci) — prod runs Prometheus "
+      f"v{DEV_PIN}")
+print(f"alert files: {len(alert_files)}   covered by a test file: "
+      f"{len(alert_files) - len(GAP_FILES)}   with NO test file: {len(GAP_FILES)}")
+print(f"alert rules: {alerts_total}   unit-tested: {covered_total}   "
+      f"NOT unit-tested: {alerts_total - covered_total}")
+
+if GAP_FILES:
+    print("\nDECLARED GAPS — alert files nothing tests at all (shrink-only register; each is a")
+    print("rule nothing has ever evaluated, NOT a rule known to work):")
+    for g in GAP_FILES:
+        print(f"  - {g}  ({len(alert_files[g])} alert(s))")
+if UNTESTED_ALERTS:
+    print("\nDECLARED GAPS — individual alerts inside a covered file that nothing asserts on:")
+    for f, n in sorted(UNTESTED_ALERTS):
+        print(f"  - {f}  {n}")
+
+print()
+if not PROMTOOL and not FAILURES:
+    print("check SKIPPED (exit 3, NOT a pass): promtool is not on PATH, so NO alert rule was "
+          "parsed and NO unit test was evaluated.", file=sys.stderr)
+    print(f"  promtool is pinned at v{DEV_PIN} in infra/devcontainer/versions.env + "
+          f"ci/versions.env.", file=sys.stderr)
+    print("  Run the gate in the pinned toolbox (./infra/devcontainer/dev.sh build, then "
+          "make -C ci gate), or set PROMTOOL=/path/to/promtool.", file=sys.stderr)
+    print(f"  The {CHECKS} offline assertions above (pins, lockstep, one harness, no run-time "
+          f"engine fetch, the gap register) DID run and passed.", file=sys.stderr)
+    print("  This test declares scope: whole-repo, so the runner reports rc 3 — UNWIRED, never "
+          "green.", file=sys.stderr)
+    raise SystemExit(3)
+
+if not FAILURES:
+    print(f"check OK: alert-rules-unit-tested — {CHECKS} assertions "
+          f"({covered_total}/{alerts_total} alert rules unit-tested, "
+          f"{len(GAP_FILES)} files with no test file, all declared) (R-OBS-04, R-TEST-02)")
+    raise SystemExit(0)
+print(f"CHECK FAIL (alert-rules-unit-tested): {len(FAILURES)} failed, "
+      f"{CHECKS - len(FAILURES)} passed", file=sys.stderr)
+for f in FAILURES:
+    print(f"  FAIL {f}", file=sys.stderr)
+raise SystemExit(1)
+PY
@@ -0,0 +1,89 @@
+# =============================================================================
+# L0 STATIC — every alert's runbook_url resolves to a runbook that is actually served
+# Catalog: docs/14 L0 row ("Pre-apply, in CI") — runs WITHOUT a cluster.
+#
+# Every platform-health alert rule in this repo carries
+# `runbook_url: "https://${BASE_DOMAIN}/runbooks/<name>"` — 42 annotations across four files, over 34
+# distinct names. For the whole of phases 4-6 there was NO runbooks/ directory and NO HTTPRoute serving
+# that path: an in-cluster probe of https://home.keithjackson.dev/runbooks/node-down returned HTTP 404.
+# So an alert reaching a human handed them a dead link at the one moment documentation is read, while the
+# annotation made the problem look solved — the same green-surface-over-absent-mechanism class as the
+# import Job that reported success while storing placeholder secrets, and the guard whose glob silently
+# stopped matching.
+#
+# The link is served now (runbooks/, clusters/base/runbooks.yaml). This test is the guard that keeps it
+# true, and it asserts BOTH halves of the claim because the regression is silent in both directions: an
+# alert with a new runbook_url and no runbook links to a 404, AND a runbook committed without its
+# configMapGenerator entry is in git, reviewed, merged — and still 404s in the cluster. "The file exists"
+# and "the URL resolves" are different claims; only the second one helps an operator.
+#
+# GIVEN every `runbook_url` annotation on every PrometheusRule in the repo,
+# WHEN  each is parsed out of git and resolved against runbooks/,
+# THEN  (1) each URL has EXACTLY the shape the server resolves — https://${BASE_DOMAIN}/runbooks/<name>,
+#           the ${BASE_DOMAIN} token (never a literal hostname), no `.md`, no trailing slash, no query;
+#       (2) every referenced <name> has a runbooks/<name>.md in git;
+#       (3) each runbook clears a QUALITY FLOOR — the four operator sections, a real body, and the
+#           dev-container kubectl invocation with --context k3s-prod — so a stub cannot satisfy (2) and
+#           make the link look fixed while still helping nobody;
+#       (4) every runbook is PROJECTED INTO THE SERVER by runbooks/kustomization.yaml's
+#           configMapGenerator under the extensionless key the URL asks for;
+#       (5) route, listener and server agree with the annotations (PathPrefix == the annotations' prefix,
+#           a sectionName that platform/gateway/gateway.yaml actually defines, the namespace opted in to
+#           the Gateway, and an nginx location for that same prefix with a text/plain default_type);
+#       (6) the Flux tier is wired into clusters/base AND declares NO postBuild.substituteFrom —
+#           substitution would run envsubst over the runbook prose and silently empty every `${...}`
+#           shell example in it (it fails open: DECISIONS-LOG 2026-09-01, the emptied Cilium
+#           k8sServiceHost), and the flux-postbuild-substitution check cannot see it because that check
+#           scans files reachable through `resources:`, not configMapGenerator inputs;
+#   AND (7) the check is LOAD-BEARING: this Test DECLARES
+#           `conformance.home.k3s/scope: whole-repo`, so ci/l0.sh Stage 3b's
+#           `--include-scope whole-repo` unions it into EVERY gate invocation rather than only the runs
+#           whose touched requirements happen to include R-OBS-04; and ci/gate.sh sets the merge block
+#           when the l0 stage fails. A SKIP of a scope-declaring check is UNWIRED, never green.
+#
+# STATUS: EXECUTABLE. `check.sh` is a pure offline assertion script (standard library only);
+# conformance/run.sh --layer l0 and ci/l0.sh run it directly, and this Chainsaw Test wraps the SAME
+# script.
+#
+# NOT proven (named in check.sh's header): this does not FETCH the URL. That it returns HTTP 200 with
+# real content was proven by an in-cluster probe recorded in the commit message; a live probe needs a
+# cluster, which L0 by definition does not have. What is asserted here is every static precondition for
+# that 200. It also does not judge whether a runbook is correct or current — (3) is a floor, not a
+# review — and it does not prove Alertmanager delivers the annotation to a human (that is the L3
+# `alerting` test). R-OBS-04 is tagged for the narrow slice only: the platform's own health alerts carry
+# runbook links that resolve to real, served procedure rather than to a 404.
+# =============================================================================
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: alert-runbooks-resolvable
+  labels:
+    conformance.home.k3s/R-OBS-04: "true"
+  annotations:
+    conformance.home.k3s/requirements: "R-OBS-04"
+    conformance.home.k3s/layer: "L0"
+    # WHOLE-REPO SCOPE — this is what makes the check unconditional. Stage 3b of ci/l0.sh runs
+    # `conformance/run.sh --layer l0 --include-scope whole-repo`, which UNIONS every test carrying this
+    # annotation into the selection regardless of which requirements the change touched. That union is
+    # load-bearing here: ci/touched-requirements.sh maps platform/monitoring/* to "R-OBS-01 R-OBS-02" —
+    # NOT R-OBS-04 — and maps platform/kubevirt/* and runbooks/* to nothing at all, so the single most
+    # likely breaking change (adding an alert with a runbook_url, or adding a runbook without its
+    # configMapGenerator entry) attributes a requirement set that would otherwise FILTER THIS CHECK OUT
+    # of exactly the change that introduces the bug. Declaring the scope replaces the hand-written
+    # per-test ci/l0.sh stage that this repo used to need (and that nobody remembered to add).
+    conformance.home.k3s/scope: "whole-repo"
+    conformance.home.k3s/safety-critical: "false"
+    conformance.home.k3s/executable: "true"
+    conformance.home.k3s/intent: >-
+      Every runbook_url on every alert rule resolves to a runbook that exists in git, clears a quality
+      floor, and is actually projected into the server that answers that path — so an alert can never
+      hand an operator a dead link.
+spec:
+  steps:
+    - name: audit-every-alert-runbook-link
+      description: >-
+        Parse every runbook_url out of every PrometheusRule and assert the runbook exists, is real, is
+        served at that exact path, and that the serving tier is wired and unsubstituted.
+      try:
+        - script:
+            content: bash ./check.sh
@@ -0,0 +1,415 @@
+#!/usr/bin/env bash
+# =============================================================================
+# L0 static check (offline, no cluster) — alert-runbooks-resolvable
+# Serves: R-OBS-04 ("The platform alerts on its own health (nodes, storage, GitOps, certs,
+#         VPN)." — spec docs/10-observability-and-alerting.md)
+#
+# WHY THIS EXISTS — A DEAD LINK IN AN ALERT IS WORSE THAN NO LINK
+# --------------------------------------------------------------
+# Every platform-health alert rule in this repo carries
+#   runbook_url: "https://${BASE_DOMAIN}/runbooks/<name>"
+# 42 such annotations across four files, over 34 distinct names. For the whole of phases 4-6
+# there was NO runbooks/ directory and NO HTTPRoute serving that path: a live in-cluster probe
+# of https://home.keithjackson.dev/runbooks/node-down returned HTTP 404. So an alert reaching a
+# human at 3am handed them a link that fails, at the one moment the documentation is read. The
+# annotation LOOKED like the problem was solved, which is the specific failure this repo keeps
+# finding (an import Job that reports success while storing placeholder secrets; a guard whose
+# glob silently stopped matching) — a green-looking surface over an absent mechanism.
+#
+# The link is now served (runbooks/, clusters/base/runbooks.yaml). This check is the guard that
+# keeps it true, because the regression is SILENT IN BOTH DIRECTIONS and nothing else catches it:
+#   * add an alert with a new runbook_url and forget the runbook  -> that alert links to a 404,
+#     and no test, lint, render or policy notices;
+#   * write runbooks/<name>.md but forget to add it to the ConfigMap generator -> the file is in
+#     git, reviewable, apparently done, and the URL still 404s in the cluster. "The file exists"
+#     and "the URL resolves" are different claims and only the second one helps an operator.
+# Both halves are asserted below, which is why this check reaches past the markdown into the
+# kustomization, the HTTPRoute, the nginx config and the Flux tier.
+#
+# GIVEN the repository as authored,
+# WHEN  every `runbook_url` annotation on every PrometheusRule is parsed out of git,
+# THEN  (1) each URL has EXACTLY the shape the server resolves —
+#           https://${BASE_DOMAIN}/runbooks/<name>, `${BASE_DOMAIN}` as the token (never a literal
+#           hostname: a literal is how prod was authored to serve dev's hostnames, see the
+#           ServiceDefinition schema's note), no `.md` suffix, no trailing slash, no query;
+#       (2) every referenced <name> has a runbooks/<name>.md in git;
+#       (3) each runbook clears a QUALITY FLOOR — the four operator sections, a real body, and the
+#           dev-container kubectl invocation — so a one-line stub cannot satisfy (2) and make the
+#           link look fixed while still helping nobody (the failure mode this check is most likely
+#           to be defeated by is a placeholder file, not a missing one);
+#       (4) every runbook markdown file is actually PROJECTED INTO THE SERVER by
+#           runbooks/kustomization.yaml's configMapGenerator, under the EXTENSIONLESS key the URL
+#           asks for — the "exists in git but 404s in the cluster" half;
+#       (5) the route and the server agree with the annotations: the HTTPRoute's PathPrefix is the
+#           prefix the URLs use, it attaches to a Gateway listener that actually exists, its
+#           namespace is opted in to that Gateway, and the nginx config answers that same prefix;
+#       (6) the Flux tier that reconciles all of it is wired into clusters/base AND declares NO
+#           postBuild.substituteFrom — substitution here would run envsubst over the runbook prose
+#           and silently empty every `${...}` shell example in it (it fails open: DECISIONS-LOG
+#           2026-09-01, the emptied Cilium k8sServiceHost);
+#   AND (7) this check is LOAD-BEARING: ci/l0.sh runs it on every gate run and ci/gate.sh sets the
+#           merge block when the l0 stage fails.
+#
+# WHY (7) IS AN UNCONDITIONAL ci/l0.sh STAGE and not left to the requirement-scoped run: Stage 3b
+# scopes `conformance/run.sh --layer l0` to the TOUCHED requirements (R-TEST-03), and
+# ci/touched-requirements.sh maps platform/monitoring/* to "R-OBS-01 R-OBS-02" — NOT R-OBS-04 — and
+# maps platform/kubevirt/* and runbooks/* to nothing at all. So the single most likely breaking
+# change (adding an alert with a runbook_url to platform/monitoring/alerts.yaml, or adding a
+# runbook and forgetting the generator entry) attributes a requirement set that would FILTER THIS
+# CHECK OUT. Declaring `conformance.home.k3s/scope: whole-repo` makes ci/l0.sh Stage 3b union it into
+# EVERY gate invocation instead; a SKIP of a scope-declaring check is UNWIRED, never green.
+#
+# WHAT THIS DOES *NOT* PROVE (honest gaps — this is a STATIC check):
+#   - It does not fetch the URL. That it returns HTTP 200 with real content was proven by an
+#     in-cluster probe (recorded in the commit message and DECISIONS-LOG); a live probe needs a
+#     cluster, which L0 by definition does not have. What is asserted here is every static
+#     precondition for that 200: the file, its projection, the key name, the route, the prefix.
+#   - It does not judge whether a runbook is CORRECT or current. (3) is a floor, not a review: it
+#     can tell a stub from a runbook, not a good runbook from a stale one. Nothing automatable can.
+#   - It does not prove Alertmanager actually delivers the annotation to a human. That is the L3
+#     `alerting` test.
+#   - It does not read ../home-network-k3s. The spec is read-only (R-TEST-06) and is not consulted.
+# =============================================================================
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "${DIR}/../../../.." && pwd)"        # repo root
+PYTHON="${PYTHON:-python3}"
+
+# Honest SKIP (never green) if there are no alert rules at all — nothing to audit yet.
+if ! grep -rl 'kind: PrometheusRule' "${ROOT}/platform" >/dev/null 2>&1; then
+  echo "check SKIPPED: no PrometheusRule found under platform/ — no alert rules to audit" >&2
+  exit 3
+fi
+
+cd "${ROOT}"
+"${PYTHON}" - "${ROOT}" <<'PY'
+"""Static audit: every alert runbook_url resolves to a runbook that is actually served.
+
+Pure standard library, no PyYAML — the same constraint and the same style as the neighbouring
+L0 checks (lib/coverage.py, lib/status.py). Every parse contract is documented at its parser;
+all of them are line-constrained shapes in hand-authored manifests.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(sys.argv[1])
+sys.dont_write_bytecode = True          # keep __pycache__ out of the tracked tree
+
+FAILURES: list[str] = []
+ADVISORIES: list[str] = []
+CHECKS = 0
+
+
+def check(cond, msg):
+    global CHECKS
+    CHECKS += 1
+    if not cond:
+        FAILURES.append(msg)
+
+
+def read(p: Path) -> str:
+    try:
+        return p.read_text()
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+# =============================================================== (1) parse the annotations
+# Parse contract: `runbook_url:` is an annotation on a Prometheus alerting rule, authored one per
+# line as `runbook_url: "<url>"` (single or double quoted, or bare). Only files that declare
+# `kind: PrometheusRule` are scanned, so a runbook_url quoted inside this check or inside prose
+# elsewhere in the repo is not mistaken for an alert annotation. Commented-out lines are skipped:
+# platform/monitoring/alerts.yaml carries a `# runbook_url points at a docs base` header comment.
+SCOPE_DECL_RE = r"^\s*conformance\.home\.k3s/scope:\s*[\"\']?whole-repo"
+RUNBOOK_URL_RE = re.compile(r"""^\s*runbook_url:\s*["']?([^"'\s#]+)["']?\s*$""")
+
+# NESTED WORKTREES: skip dot-DIRECTORIES (.git, .claude) while still matching dot-FILES such
+# as .sops.yaml. .claude/worktrees/agent-*/ holds full repo copies for isolated agent runs, so
+# a bare rglob from ROOT audited up to 18 duplicates of every file — which both invents FAILs
+# and, worse, can satisfy an "something declares X" check from a copy rather than real source.
+# Same fix as egress-paths-selected-by-rules. .claude/ is gitignored (.gitignore:43).
+rule_files = sorted(
+    p for p in ROOT.rglob("*.yaml")
+    if not any(part.startswith(".") for part in p.relative_to(ROOT).parent.parts) and "kind: PrometheusRule" in read(p)
+)
+check(len(rule_files) > 0,
+      "no file declaring `kind: PrometheusRule` found — the parser or the repo layout changed; "
+      "this check would silently audit nothing")
+
+# url -> [ "<relpath>:<lineno>", ... ]
+refs: dict[str, list[str]] = {}
+for f in rule_files:
+    rel = f.relative_to(ROOT)
+    for lineno, line in enumerate(read(f).splitlines(), 1):
+        if line.lstrip().startswith("#"):
+            continue
+        m = RUNBOOK_URL_RE.match(line)
+        if m:
+            refs.setdefault(m.group(1), []).append(f"{rel}:{lineno}")
+
+n_annotations = sum(len(v) for v in refs.values())
+check(n_annotations > 0,
+      "no runbook_url annotation parsed out of any PrometheusRule — the parser contract broke; "
+      "this check would pass vacuously while every alert link rots")
+
+# ---- URL SHAPE. The server resolves exactly one shape. Anything else is a link that 404s even
+# though a file with a plausible name exists, so shape is a failure, not a style note.
+URL_RE = re.compile(r"^https://\$\{BASE_DOMAIN\}/(runbooks)/([a-z0-9][a-z0-9-]*)$")
+names: dict[str, list[str]] = {}        # runbook name -> annotation sites
+prefixes: set[str] = set()
+for url, sites in sorted(refs.items()):
+    m = URL_RE.match(url)
+    check(m is not None,
+          f"runbook_url '{url}' ({', '.join(sites)}) is not the shape this platform serves. "
+          f"Required: https://${{BASE_DOMAIN}}/runbooks/<name> — the ${{BASE_DOMAIN}} TOKEN (never a "
+          f"literal hostname: a literal is how prod got authored to serve dev's public names), a "
+          f"lowercase-hyphen <name>, and NO '.md' suffix, trailing slash or query. The runbook "
+          f"server maps the URL path straight onto an extensionless ConfigMap key, so any other "
+          f"shape is a 404 no matter which files exist")
+    if m:
+        prefixes.add(m.group(1))
+        names.setdefault(m.group(2), []).extend(sites)
+
+check(len(prefixes) <= 1,
+      f"alert annotations use more than one runbook path prefix ({sorted(prefixes)}); the single "
+      f"HTTPRoute + nginx location can only serve one, so the others are dead links")
+PREFIX = (sorted(prefixes) or ["runbooks"])[0]
+
+# =================================================== (2)(3) the runbooks exist and are real
+RUNBOOK_DIR = ROOT / PREFIX
+check(RUNBOOK_DIR.is_dir(),
+      f"{PREFIX}/ is not a directory in this repo, so every one of the {n_annotations} "
+      f"runbook_url annotations is a dead link")
+
+# The quality floor. (2) alone is satisfiable by `touch runbooks/node-down.md`, which makes the
+# link resolve and still abandons the operator — a worse outcome than the 404, because the 404 at
+# least told the truth. These four sections are the operator's path through an incident: what the
+# alert means HERE, what to type first, what is probably wrong, and when to stop. `dev.sh` +
+# `--context k3s-prod` are required because kubectl does not work on the workstation at all
+# (the toolchain lives only in the pinned dev container) and because dev.sh defaults its
+# current-context to k3s-DEV — a runbook that omits the context teaches the reader to answer
+# questions about the wrong cluster during an incident on this one.
+REQUIRED_SECTIONS = (
+    "## What this means here",
+    "## First commands",
+    "## Likely causes, most likely first",
+    "## When to escalate or stop",
+)
+MIN_BYTES = 1500
+
+for name, sites in sorted(names.items()):
+    md = RUNBOOK_DIR / f"{name}.md"
+    if not md.is_file():
+        check(False,
+              f"runbook '{name}' does not exist: {md.relative_to(ROOT)} is missing, but "
+              f"{len(sites)} alert annotation(s) link to it ({', '.join(sites[:3])}"
+              f"{', ...' if len(sites) > 3 else ''}). An alert firing now hands the operator a 404. "
+              f"Write {PREFIX}/{name}.md (see {PREFIX}/README.md for the required sections)")
+        continue
+    body = read(md)
+    check(len(body) >= MIN_BYTES,
+          f"{md.relative_to(ROOT)} is {len(body)} bytes, under the {MIN_BYTES}-byte floor — a stub "
+          f"that makes the link resolve while still helping nobody is worse than the 404 it "
+          f"replaced, because it looks fixed")
+    for sec in REQUIRED_SECTIONS:
+        check(sec in body,
+              f"{md.relative_to(ROOT)} has no '{sec}' section — the four operator sections are what "
+              f"make this a runbook rather than a restatement of the alert name")
+    check("dev.sh" in body,
+          f"{md.relative_to(ROOT)} never mentions dev.sh — kubectl does not exist on the "
+          f"workstation; every command in a runbook here must be runnable as "
+          f"`infra/devcontainer/dev.sh run bash -c '...'` and the runbook must say so")
+    check("--context k3s-prod" in body,
+          f"{md.relative_to(ROOT)} never passes --context k3s-prod — dev.sh merges both clusters "
+          f"and picks a current-context PER INVOCATION — a default that has already changed once "
+          f"(k3s-dev until dev was decommissioned on 2026-09-13, k3s-prod now). A context-less command "
+          f"silently answers about whichever cluster the default happens to be, in the middle of an "
+          f"incident")
+
+# ADVISORY, not a failure: a runbook nothing links to yet. Writing the runbook BEFORE the alert is
+# the right order, and the repo's precedent for "authored but unreferenced" is advisory (see the
+# dead-knob advisory in flux-postbuild-substitution/check.sh).
+served_extra = {"README"}
+if RUNBOOK_DIR.is_dir():
+    for md in sorted(RUNBOOK_DIR.glob("*.md")):
+        stem = md.stem
+        if stem in served_extra or stem in names:
+            continue
+        ADVISORIES.append(f"{md.relative_to(ROOT)} is a runbook no alert links to (written ahead of "
+                          f"its alert, or the alert was removed — advisory, not a failure)")
+
+# ================================= (4) every runbook is PROJECTED INTO THE SERVER, not just in git
+# THIS IS THE HALF A FILE-EXISTENCE CHECK WOULD MISS. The pod serves a ConfigMap, not the git tree.
+# Parse contract: runbooks/kustomization.yaml declares one configMapGenerator whose `files:` entries
+# are `- <key>=<file>.md`, one per line. The key is EXTENSIONLESS on purpose (the URL carries no
+# `.md`, and the ConfigMap volume mount turns each key into a file the nginx root resolves directly).
+KUST = RUNBOOK_DIR / "kustomization.yaml"
+check(KUST.is_file(), f"{PREFIX}/kustomization.yaml is missing — the Flux tier renders nothing and "
+                      f"every runbook 404s no matter what is in git")
+GEN_FILE_RE = re.compile(r"^\s*-\s*([A-Za-z0-9._-]+)=([A-Za-z0-9._/-]+\.md)\s*(?:#.*)?$")
+generated: dict[str, str] = {}
+kust_text = read(KUST)
+if kust_text:
+    check("configMapGenerator:" in kust_text,
+          f"{PREFIX}/kustomization.yaml has no configMapGenerator — the runbook markdown is not "
+          f"rendered into the ConfigMap the server mounts")
+    for line in kust_text.splitlines():
+        if line.lstrip().startswith("#"):
+            continue
+        m = GEN_FILE_RE.match(line)
+        if m:
+            generated[m.group(1)] = m.group(2)
+    check(len(generated) > 0,
+          f"{PREFIX}/kustomization.yaml declares no `<key>=<file>.md` generator entries — the "
+          f"parser contract broke, or the markdown is being added with implicit keys (which would "
+          f"carry the '.md' suffix the alert URLs do NOT have, so every link would 404)")
+
+for name in sorted(names):
+    check(generated.get(name) == f"{name}.md",
+          f"runbook '{name}' is not projected into the server: {PREFIX}/kustomization.yaml has no "
+          f"configMapGenerator entry `- {name}={name}.md`. The file can be in git, reviewed and "
+          f"merged and the URL still returns 404 — 'the file exists' and 'the URL resolves' are "
+          f"different claims")
+
+# And the reverse, so a generator entry cannot point at a file that is not there.
+for key, fname in sorted(generated.items()):
+    check((RUNBOOK_DIR / fname).is_file(),
+          f"{PREFIX}/kustomization.yaml generates key '{key}' from {PREFIX}/{fname}, which does not "
+          f"exist — `kustomize build` fails, so the WHOLE tier stops reconciling and every runbook "
+          f"goes stale at once")
+
+# ============================== (5) the route, the listener and the server agree with the URLs
+ROUTE = RUNBOOK_DIR / "serving" / "httproute.yaml"
+NGINX = RUNBOOK_DIR / "serving" / "nginx-config.yaml"
+NS = RUNBOOK_DIR / "serving" / "namespace.yaml"
+GATEWAY = ROOT / "platform" / "gateway" / "gateway.yaml"
+
+route_text = read(ROUTE)
+check(bool(route_text), f"{PREFIX}/serving/httproute.yaml is missing — nothing routes the "
+                        f"/{PREFIX} prefix to the server")
+# Parse contract: a single HTTPRoute with one PathPrefix match and one parentRefs entry naming a
+# listener via sectionName; hand-authored, one key per line.
+m_path = re.search(r"^\s*type:\s*PathPrefix\s*$\n\s*value:\s*(\S+)\s*$", route_text, re.M)
+check(m_path is not None and m_path.group(1) == f"/{PREFIX}",
+      f"{PREFIX}/serving/httproute.yaml does not match PathPrefix /{PREFIX} "
+      f"(found {m_path.group(1) if m_path else 'no PathPrefix match'}). The alert annotations point "
+      f"at /{PREFIX}/<name>; if the route's prefix drifts from the annotations the links 404 while "
+      f"both files look individually correct")
+m_sec = re.search(r"^\s*sectionName:\s*(\S+)", route_text, re.M)
+check(m_sec is not None,
+      f"{PREFIX}/serving/httproute.yaml declares no parentRefs sectionName. The apex host needs the "
+      f"dedicated apex listener: the wildcard `*.${{BASE_DOMAIN}}` listener does NOT match the bare "
+      f"apex, so a route without sectionName binds nothing and serves nothing")
+if m_sec:
+    listener = m_sec.group(1)
+    gw = read(GATEWAY)
+    check(re.search(rf"^\s*-\s*name:\s*{re.escape(listener)}\s*$", gw, re.M) is not None,
+          f"{PREFIX}/serving/httproute.yaml attaches to Gateway listener '{listener}', which "
+          f"platform/gateway/gateway.yaml does not define — the route would report NotAllowed and "
+          f"never serve")
+# An HTTPRoute with no `hostnames:` inherits the listener's hostname, which is how this tier avoids
+# needing Flux substitution (see (6)). Either form is routable; a LITERAL hostname is not acceptable,
+# for the same reason the schema forbids it in a ServiceDefinition.
+m_host = re.search(r"^\s*hostnames:\s*$\n\s*-\s*(\S+)", route_text, re.M)
+check(m_host is None or "${BASE_DOMAIN}" in m_host.group(1),
+      f"{PREFIX}/serving/httproute.yaml hardcodes hostname '{m_host.group(1) if m_host else ''}' — "
+      f"use the ${{BASE_DOMAIN}} token, or omit `hostnames:` entirely and inherit the listener's")
+
+ns_text = read(NS)
+check('gateway-access: "shared"' in ns_text or "gateway-access: shared" in ns_text,
+      f"{PREFIX}/serving/namespace.yaml does not carry gateway-access=shared — the shared Gateway "
+      f"selects namespaces by that label, so without it the HTTPRoute is refused attachment")
+
+nginx_text = read(NGINX)
+check(f"location /{PREFIX}/" in nginx_text,
+      f"{PREFIX}/serving/nginx-config.yaml has no `location /{PREFIX}/` block — the route would "
+      f"deliver the request and the server would answer 404 for every runbook")
+check("default_type" in nginx_text and "text/plain" in nginx_text,
+      f"{PREFIX}/serving/nginx-config.yaml does not force a text/plain default_type. The ConfigMap "
+      f"keys are EXTENSIONLESS, so with the stock MIME table nginx serves them as "
+      f"application/octet-stream and a browser DOWNLOADS the runbook instead of showing it")
+
+# ====================================== (6) the Flux tier is wired, and is NOT substituted
+FLUX = ROOT / "clusters" / "base" / f"{PREFIX}.yaml"
+BASE_KUST = ROOT / "clusters" / "base" / "kustomization.yaml"
+flux_text = read(FLUX)
+check(bool(flux_text),
+      f"clusters/base/{PREFIX}.yaml is missing — nothing reconciles {PREFIX}/ into the cluster, so "
+      f"the runbooks exist in git and the URL still 404s")
+check(re.search(rf"^\s*path:\s*\./{re.escape(PREFIX)}\s*$", flux_text, re.M) is not None,
+      f"clusters/base/{PREFIX}.yaml does not set `path: ./{PREFIX}`")
+check(re.search(r"^\s*wait:\s*false\s*$", flux_text, re.M) is not None,
+      f"clusters/base/{PREFIX}.yaml is not wait:false — a leaf web server that can be legitimately "
+      f"unhealthy must never gate the reconcile chain (DECISIONS-LOG: 'Headlamp gating stall')")
+# Strip comments before testing: this file's own comment block EXPLAINS at length why
+# substituteFrom must never be added here, and a naive substring test would fire on the warning.
+flux_code = "\n".join(l for l in flux_text.splitlines() if not l.lstrip().startswith("#"))
+check("substituteFrom" not in flux_code,
+      f"clusters/base/{PREFIX}.yaml declares postBuild.substituteFrom. It MUST NOT: this tier "
+      f"renders documentation into a ConfigMap, and Flux's envsubst would run over the prose and "
+      f"silently EMPTY every `${{...}}` shell example in every runbook — it fails open, so the "
+      f"Kustomization would still report Ready (DECISIONS-LOG 2026-09-01, the emptied Cilium "
+      f"k8sServiceHost). The flux-postbuild-substitution check cannot see this: it scans files "
+      f"reachable through `resources:`, not configMapGenerator inputs")
+check(re.search(rf"^\s*-\s*{re.escape(PREFIX)}\.yaml\b", read(BASE_KUST), re.M) is not None,
+      f"clusters/base/kustomization.yaml does not list {PREFIX}.yaml — the Flux Kustomization is "
+      f"authored and never applied, which is the 'looks done, is absent' class this repo has been "
+      f"bitten by repeatedly")
+
+# ============================================ (7) this check is load-bearing in the merge gate
+L0 = read(ROOT / "ci" / "l0.sh")
+GATE = read(ROOT / "ci" / "gate.sh")
+# THIS CHECK IS LOAD-BEARING — asserted against the DECLARATIVE mechanism, in two halves.
+# It is not enough that check.sh exists: the merge gate must SELECT it on every run. The repo used to
+# get that with a hand-written "UNCONDITIONAL" stage per whole-repo check in ci/l0.sh, hardcoding the
+# path; those stages are gone, because the next whole-repo invariant only got one if somebody
+# REMEMBERED to write it. The property is now DECLARED by the test and HONOURED by the gate, so both
+# halves are asserted — neither alone is sufficient. The mechanism itself (that the union really
+# selects, and that a scope-declared SKIP exits 3 rather than passing green) is proven end-to-end and
+# falsifiably by conformance/tests/l0-static/whole-repo-invariants-wired.
+SELF_YAML = (ROOT / "conformance" / "tests" / "l0-static" / "alert-runbooks-resolvable"
+             / "chainsaw-test.yaml")
+SELF = read(SELF_YAML)
+check(re.search(SCOPE_DECL_RE, SELF, re.M) is not None,
+      "alert-runbooks-resolvable/chainsaw-test.yaml does not declare "
+      "conformance.home.k3s/scope: whole-repo, so the merge gate selects this check only when a "
+      "change happens to touch a requirement it is labelled with. ci/touched-requirements.sh maps "
+      "platform/monitoring/* to 'R-OBS-01 R-OBS-02' (NOT R-OBS-04) and maps platform/kubevirt/* and "
+      "runbooks/* to nothing at all — so adding an alert with a new runbook_url, or adding a runbook "
+      "without its configMapGenerator entry, would be filtered out of exactly the change that "
+      "introduces the dead link")
+check("--include-scope" in L0,
+      "ci/l0.sh no longer passes --include-scope to the conformance runner, so the L0 stage is a "
+      "purely requirement-scoped run again and the scope annotation above is inert decoration — this "
+      "check would then run only by coincidence")
+check(re.search(r"^for s in .*\bl0\b.*; do", GATE, re.M) and re.search(r"fail\).*BLOCK=1", GATE),
+      "ci/gate.sh does not set the merge block when the l0 stage fails")
+
+# ======================================================================== report
+print(f"Alert runbook inventory: {n_annotations} runbook_url annotation(s) across "
+      f"{len(rule_files)} PrometheusRule file(s) -> {len(names)} distinct runbook(s), "
+      f"prefix /{PREFIX}")
+missing = sorted(n for n in names if not (RUNBOOK_DIR / f"{n}.md").is_file())
+print(f"  runbooks present: {len(names) - len(missing)}/{len(names)}   "
+      f"projected into the ConfigMap: {sum(1 for n in names if generated.get(n) == f'{n}.md')}/{len(names)}")
+if missing:
+    print(f"  MISSING: {', '.join(missing)}", file=sys.stderr)
+
+if ADVISORIES:
+    print("\nADVISORIES (not failures):")
+    for a in ADVISORIES:
+        print(f"  - {a}")
+
+print()
+if not FAILURES:
+    print(f"check OK: alert-runbooks-resolvable — {CHECKS} assertions (R-OBS-04)")
+    raise SystemExit(0)
+print(f"CHECK FAIL (alert-runbooks-resolvable): {len(FAILURES)} failed, "
+      f"{CHECKS - len(FAILURES)} passed", file=sys.stderr)
+for f in FAILURES:
+    print(f"  FAIL {f}", file=sys.stderr)
+raise SystemExit(1)
+PY
@@ -77,6 +77,14 @@ metadata:
  annotations:
    conformance.home.k3s/requirements: "R-SEC-03"
    conformance.home.k3s/layer: "L0"
+    # WHOLE-REPO SCOPE. This is a META-invariant over the ENTIRE conformance suite: the five
+    # spec-named proofs must each still have an EXECUTABLE test at the right layer, with a
+    # pass sentinel, resolvable by the documented command. Every one of its inputs lives under
+    # conformance/, which ci/touched-requirements.sh keys to R-TEST-01..04 — never to R-SEC-03.
+    # So downgrading conformance/tests/l3-fault-injection/dr-restore to a scaffold attributes
+    # R-STATE-03/R-TEST-*, and requirement-scoped selection drops the one check that notices
+    # the audit evidence just stopped being producible.
+    conformance.home.k3s/scope: "whole-repo"
    conformance.home.k3s/safety-critical: "false"
    conformance.home.k3s/executable: "true"
    conformance.home.k3s/intent: >-
@@ -250,6 +250,11 @@ try:
    sys.dont_write_bytecode = True
    import record_run as rr                                   # noqa: E402

+    # status.py owns the latest-wins rule; import it rather than reimplementing it, so the two
+    # cannot disagree about which rows are live evidence.
+    import status as _st                                        # noqa: E402
+    rr_latest_by_test = _st.latest_by_test
+
    smap = rr.sentinel_map(CONF / "tests")
    check(len(smap) >= 10,
          f"record_run.py's sentinel map contains {len(smap)} test(s) — the parser lost its "
@@ -386,6 +391,15 @@ try:
        check(not bad,
              f"conformance/runs/ledger.jsonl has unparsable line(s) {bad} — the audit record "
              "is not machine-readable, so no proof can be derived from it")
+        # Which rows are HONOURED: status.py resolves duplicates latest-wins (latest_by_test),
+        # so a superseded row is not evidence of anything. The dirty-tree assertion below is
+        # therefore scoped to honoured rows. Without that scoping, ONE historical dirty row reds
+        # this gate permanently even after a clean re-run of the same test — and a dirty-then-
+        # clean sequence is the normal shape of "noticed the tree was dirty, fixed it, re-ran".
+        # The row is still kept in the ledger and its run.log stays committed: nothing is erased,
+        # it simply stops being treated as a live claim. Structural assertions (provenance keys,
+        # sentinel, test-still-exists) still apply to EVERY row.
+        honoured_ids = {id(v) for v in rr_latest_by_test(rows).values()}
        for r in rows:
            for key in ("ts_utc", "git_sha", "test", "requirements", "junit_result", "proof",
                        "run_id"):
@@ -393,13 +407,22 @@ try:
                      f"a ledger row for {r.get('test', '?')!r} lacks {key!r} — a row without "
                      "provenance cannot be audited")
            if r.get("proof") == "proven":
-                check(bool(r.get("sentinel")),
-                      f"a ledger row claims `proven` for {r.get('test')!r} with NO sentinel — "
-                      "the sentinel is the only thing separating a real pass from a self-skip")
+                # L0/L1 rows are recorded proven WITHOUT a sentinel, deliberately, by
+                # record_run.py's own SENTINEL_EXEMPT_LAYERS: run_l1_offline.py renders skips as
+                # JUnit <skipped/>, so those layers have no pass token to attribute. This
+                # assertion had NO layer exemption, so the two halves of the harness contradicted
+                # each other — ANY `--record` run touching L0 or L1 wrote a row this gate then
+                # rejected, which meant a requirement whose verifier set includes an L1 check
+                # (R-NET-06 is one) could never be both PROVEN and L0-green. Honour the same
+                # constant rather than restating the policy here, so the two cannot drift apart.
+                if r.get("layer") not in rr.SENTINEL_EXEMPT_LAYERS:
+                    check(bool(r.get("sentinel")),
+                          f"a ledger row claims `proven` for {r.get('test')!r} with NO sentinel — "
+                          "the sentinel is the only thing separating a real pass from a self-skip")
                check(r.get("test") in smap,
                      f"a ledger row claims `proven` for {r.get('test')!r}, which is not a "
                      "test in the suite any more — a proof of something that no longer exists")
-                check("-dirty" not in str(r.get("git_sha", "")),
+                check(id(r) not in honoured_ids or "-dirty" not in str(r.get("git_sha", "")),
                      f"a ledger row claims `proven` for {r.get('test')!r} from a DIRTY tree "
                      f"({r.get('git_sha')}) — what ran is not what is committed")
    else:
@@ -76,6 +76,21 @@ metadata:
  annotations:
    conformance.home.k3s/requirements: "R-STATE-04"
    conformance.home.k3s/layer: "L0"
+    # WHOLE-REPO SCOPE — relocated verbatim from ci/l0.sh's hand-written "Stage 3e
+    # (UNCONDITIONAL)", which this annotation replaces:
+    #
+    #   The `bulk` StorageClass sat as a REPLACE-ME stub for six roadmap phases, and the only
+    #   thing keeping a multi-terabyte media library off the 3-replica `longhorn` class was four
+    #   hand-written comments in ServiceDefinitions. A bulk volume that lands on the replicated
+    #   tier does not fail loudly — Longhorn accepts the PVC and starts replicating 3x of data
+    #   three mini-PCs cannot hold.
+    #
+    #   WHY IT MUST NOT BE REQUIREMENT-SCOPED: ci/touched-requirements.sh's path map keys
+    #   NEITHER apps/* nor platform/longhorn/* to the bulk requirement. So the change most
+    #   likely to break this — moving a bulk volume onto the replicated tier, or narrowing one
+    #   export into two mounts — could attribute no requirement at all and be gated by nothing.
+    #   The invariant spans catalog/, apps/ and clusters/.
+    conformance.home.k3s/scope: "whole-repo"
    conformance.home.k3s/safety-critical: "false"
    conformance.home.k3s/executable: "true"
    conformance.home.k3s/intent: >-
@@ -83,7 +83,8 @@
 #           knob has a base default; and EVERY environment overlay supplies it — so the two
 #           clusters, which reach this storage by different addresses, cannot be served by
 #           one hardcoded value;
-#   AND (9) LOAD-BEARING + NON-VACUOUS: ci/l0.sh runs this check unconditionally and
+#   AND (9) LOAD-BEARING + NON-VACUOUS: this check DECLARES `conformance.home.k3s/scope:
+#           whole-repo`, so ci/l0.sh runs it unconditionally via --include-scope, and
 #           ci/gate.sh blocks the merge when the l0 stage fails; and the corpus is NOT
 #           empty — a repo with zero bulk volumes fails here rather than passing trivially,
 #           because a check that is satisfiable by deleting the feature proves nothing.
@@ -442,12 +443,27 @@ for tok in sorted(tokens):
 # --------------------------------------------------------------- (9) LOAD-BEARING
 L0 = (ROOT / "ci" / "l0.sh").read_text() if (ROOT / "ci" / "l0.sh").is_file() else ""
 GATE = (ROOT / "ci" / "gate.sh").read_text() if (ROOT / "ci" / "gate.sh").is_file() else ""
-check("bulk-tier-distinct-from-replicated/check.sh" in L0,
-      "ci/l0.sh does not run bulk-tier-distinct-from-replicated/check.sh. Stage 3b scopes "
-      "the conformance run to TOUCHED requirements, and ci/touched-requirements.sh maps "
-      "neither apps/* nor platform/longhorn/* to the bulk requirement — so a change that "
-      "moves a bulk volume onto the replicated tier could attribute no requirement at all "
-      "and be gated by nothing. It must be invoked directly and unconditionally")
+# THIS CHECK IS LOAD-BEARING — asserted against the DECLARATIVE mechanism.
+# It used to assert `"bulk-tier-distinct-from-replicated/check.sh" in L0`: ci/l0.sh carried a hand-written
+# "UNCONDITIONAL" stage per whole-repo check, hardcoding this path. Those stages are gone
+# (they did not scale, and the next whole-repo invariant only got one if someone REMEMBERED
+# to write it). The same property is now asserted two ways: this test DECLARES
+# `conformance.home.k3s/scope: "whole-repo"`, and ci/l0.sh unions every declaring test into
+# the run via `--include-scope`. Neither half alone is enough, so both are checked here; the
+# mechanism ITSELF (the union really selects, and a scope-declared SKIP exits 3 rather than
+# passing) is proven end-to-end and falsifiably by
+# conformance/tests/l0-static/whole-repo-invariants-wired.
+SELF_YAML = ROOT / "conformance" / "tests" / "l0-static" / "bulk-tier-distinct-from-replicated" / "chainsaw-test.yaml"
+SELF = SELF_YAML.read_text() if SELF_YAML.is_file() else ""
+check(re.search(r'^\s*conformance\.home\.k3s/scope:\s*["\']?whole-repo', SELF, re.M) is not None,
+      "bulk-tier-distinct-from-replicated/chainsaw-test.yaml does not declare "
+      'conformance.home.k3s/scope: "whole-repo", so the merge gate selects this check only '
+      "when a change happens to touch one of the requirements it is labelled with. "
+      "The path map keys NEITHER apps/* nor platform/longhorn/* to the bulk requirement, so moving a multi-terabyte bulk volume onto the 3-replica tier could attribute no requirement at all and be gated by nothing")
+check("--include-scope" in L0,
+      "ci/l0.sh no longer passes --include-scope to the conformance runner, so the L0 stage is "
+      "a purely requirement-scoped run again and the scope annotation is inert decoration — "
+      "this check would then run only by coincidence")
 check(re.search(r"^for s in .*\bl0\b.*; do", GATE, re.M) and re.search(r"fail\).*BLOCK=1", GATE),
      "ci/gate.sh does not set the merge block when the l0 stage fails")

@@ -0,0 +1,116 @@
+# =============================================================================
+# L0 STATIC — the C2 root surfaces every service the cluster runs, plus platform
+# health and controlled actions  (R-C2-01, R-C2-02)   [EXECUTABLE]
+# Catalog: docs/14 L0 row ("Pre-apply, in CI") — runs WITHOUT a cluster.
+#
+# THE REQUIREMENTS, VERBATIM (spec docs/00-vision-and-scope.md):
+#   R-C2-01  "The root `home.keithjackson.dev` MUST serve a UI that surfaces the services
+#             running in the cluster and links to them."
+#   R-C2-02  "The C2 UI MUST surface platform health (cluster, storage, GitOps, alerts) and
+#             provide controlled operational actions where safe."
+# Detail: spec docs/12-command-center-ui.md — Homepage at the root is "the primary R-C2-01
+# surface"; Headlamp is "the R-C2-02 'controlled operational actions where safe' surface";
+# Grafana is the dashboards/alerts surface; "never a raw cluster-admin kubeconfig in a browser".
+#
+# WHY L0, AND NOT L2
+# ------------------
+# The REACHABILITY half of R-C2-01 is already exercised against a live cluster:
+# l2-behavioral/gateway-ingress-reachable dials the Gateway and l2-behavioral/trusted-tls
+# verifies the certificate it serves. What no live probe can decide is the half the
+# requirement is actually about — whether the UI at the root surfaces THE SERVICES RUNNING
+# IN THE CLUSTER. Deciding that is a comparison of two SETS, and both are repository facts:
+# what git declares the cluster serves (every in-repo HTTPRoute hostname, every L4 Service
+# that publishes a hostname, every catalog ServiceDefinition) against what the dashboard's
+# ConfigMap links. A probe of the root gets HTTP 200 from a dashboard that hides half the
+# estate and cannot tell the difference.
+#
+# It is also the assertion that ROTS, in the direction nothing else notices: onboard a
+# service, forget the dashboard, and every cluster test stays green while the operator's
+# front door hides a running service. That is not a styling preference — it is exactly the
+# R-C2-01 failure mode, and this check found a live instance of it when it was written (see
+# the commit message: platform/crafty served crafty.${BASE_DOMAIN} and nothing on the root
+# linked to it).
+#
+# GIVEN the repository as git tracks it,
+# WHEN  the apex ingress, the dashboard's declared link set, every in-repo HTTPRoute, every
+#       hostname-publishing L4 Service, the versioned catalog and the platform-health
+#       surfaces are read and compared,
+# THEN — R-C2-01 —
+#       the bare apex is claimed by exactly one route, that route binds the ONE Gateway
+#       listener whose hostname matches a bare apex, the apex is a SAN on the certificate
+#       that listener terminates with, the dashboard is RECONCILED (not merely authored),
+#       FORWARD every HTTP service the repo routes is linked from the root, FORWARD every
+#       catalog `kind: container` service with a route is linked, and REVERSE every
+#       home-zone link the root offers resolves to something this repo actually serves —
+#       an HTTPRoute (L7) or a hostname-publishing LoadBalancer Service (L4);
+#     — R-C2-02 —
+#       both health surfaces docs/12 names are linked AND reconciled, the health DATA exists
+#       as code (PrometheusRule groups for cluster/nodes, storage, GitOps and cert expiry,
+#       reconciled by the platform-config tier), and actions are CONTROLLED: the console
+#       binds NO ClusterRole to its own ServiceAccount, authenticates per-user by native
+#       OIDC from a named SOPS Secret, and cluster rights arrive through OIDC GROUPS at more
+#       than one privilege level.
+#
+# STATUS: EXECUTABLE. `check.sh` is a pure offline assertion script (git ls-files + PyYAML —
+# the same dependency catalog/render.py already requires). conformance/run.sh --layer l0 and
+# ci/l0.sh run it directly; this Chainsaw Test wraps the SAME script.
+#
+# WHAT IT DOES NOT PROVE — honest gaps, restated in check.sh's own header:
+#   - That the apex answers HTTP 200, or that any tile's status ping is green. That is L2;
+#     the Gateway/TLS half is covered under R-DNS-01 / R-TLS-01.
+#   - That the C2 is access-CONTROLLED in fact. The auth assertions read a DECLARED posture,
+#     because the Gateway ext-authz attachment that would enforce forward-auth is not built
+#     anywhere in this repo (platform/homepage/httproute.yaml says so in its own header, and
+#     every forward-auth app shares the gap). Declared, not enforced — and labelled as such
+#     in the assertion text.
+#   - That an operational action in the console succeeds, or that it is audited. The
+#     assertions prove there is no shared cluster-admin identity to act with and that rights
+#     arrive per-user; the audit trail is a runtime property.
+#   - Whether a tile is USEFUL. Homepage service-widget API keys are a deliberate follow-up
+#     (platform/homepage/configmap.yaml); link presence is what R-C2-01 asks for.
+# =============================================================================
+apiVersion: chainsaw.kyverno.io/v1alpha1
+kind: Test
+metadata:
+  name: c2-root-surface
+  labels:
+    conformance.home.k3s/R-C2-01: "true"
+    conformance.home.k3s/R-C2-02: "true"
+  annotations:
+    conformance.home.k3s/requirements: "R-C2-01, R-C2-02"
+    conformance.home.k3s/layer: "L0"
+    # WHOLE-REPO SCOPE, and it is the whole point of the forward assertion.
+    #
+    # The invariant is "every service the repo routes is linked from the C2 root". Its input
+    # surface is therefore EVERY tracked manifest that can declare an HTTPRoute — apps/wave-*,
+    # platform/*, runbooks/ — not just the two components that own the C2. ci/touched-
+    # requirements.sh keys `platform/homepage/*` and `platform/headlamp/*` to nothing at all
+    # today (there is no path-map arm for either), and even with one, the change that BREAKS
+    # this invariant is the change that adds a route somewhere else: `apps/wave-1/newthing.yaml`
+    # attributes R-GITOPS-02 / R-NET-* / nothing, never R-C2-01. Requirement-scoped selection
+    # would filter this check out of exactly the change that introduces the bug — the R-TEST-03
+    # blind spot recorded in conformance/lib/common.sh.
+    #
+    # Declaring the scope is the whole fix: conformance/run.sh --include-scope whole-repo
+    # (ci/l0.sh Stage 3b) unions this test into EVERY gate invocation. Do NOT hand-add a stage
+    # to ci/l0.sh — tests/l0-static/whole-repo-invariants-wired fails the gate if anyone does.
+    # A SKIP of a scope-declaring check is rc 3 (UNWIRED), never green.
+    conformance.home.k3s/scope: "whole-repo"
+    conformance.home.k3s/safety-critical: "false"
+    conformance.home.k3s/executable: "true"
+    conformance.home.k3s/intent: >-
+      The bare apex is bound to the landing dashboard over trusted TLS and is reconciled; the
+      dashboard links every HTTP service this repo routes and every link it offers resolves to
+      something the repo serves; and the C2 surfaces platform health backed by real alert rules
+      while granting operational rights per-user through OIDC groups rather than through a
+      shared cluster-admin identity.
+spec:
+  steps:
+    - name: compare-the-c2-root-against-what-the-repo-actually-serves
+      description: >-
+        Read the apex ingress chain, the dashboard's declared links, every in-repo HTTPRoute and
+        hostname-publishing Service, the catalog, the platform-health alert rules and the
+        console's RBAC posture, and assert the two sets agree in both directions.
+      try:
+        - script:
+            content: bash ./check.sh
@@ -0,0 +1,689 @@
+#!/usr/bin/env bash
+# =============================================================================
+# L0 static check (offline, no cluster) — c2-root-surface
+#
+# Serves (spec docs/00-vision-and-scope.md; detail in docs/12-command-center-ui.md):
+#
+#   R-C2-01  "The root `home.keithjackson.dev` MUST serve a UI that surfaces the
+#             services running in the cluster and links to them."
+#   R-C2-02  "The C2 UI MUST surface platform health (cluster, storage, GitOps,
+#             alerts) and provide controlled operational actions where safe."
+#
+# WHY THIS IS AN L0 STATIC CHECK AND NOT AN L2 PROBE
+# --------------------------------------------------
+# The REACHABILITY half of R-C2-01 is already exercised against a live cluster:
+# l2-behavioral/gateway-ingress-reachable dials the Gateway and l2-behavioral/trusted-tls
+# verifies the certificate it serves. What no live probe can decide is the half the
+# requirement is actually about — whether the UI at the root surfaces THE SERVICES RUNNING
+# IN THE CLUSTER. Deciding that is a comparison of two SETS, and both are repository facts:
+# what git declares the cluster serves (every in-repo HTTPRoute hostname, every
+# hostname-publishing L4 Service, every catalog ServiceDefinition) against what the
+# dashboard's ConfigMap links. A probe of the root gets HTTP 200 from a dashboard that hides
+# half the estate and cannot tell the difference.
+#
+# It is also the assertion that ROTS, in the direction nothing else notices: onboard a
+# service, forget the dashboard, and every cluster test stays green while the operator's
+# front door hides a running service. That is not a styling preference — it is exactly the
+# R-C2-01 failure mode, and it was a LIVE defect on main when this check was written
+# (platform/crafty served crafty.${BASE_DOMAIN} and nothing on the root linked to it).
+#
+# THE RULE THIS IMPLEMENTS, in one sentence: every home-zone hostname the repository routes
+# over HTTP must be linked from the apex dashboard's configuration, every home-zone link the
+# apex dashboard offers must resolve to something the repository actually serves, and the two
+# R-C2-02 surfaces (health data + a per-user-authorized console) must be linked, reconciled
+# and backed by real alert rules.
+#
+# GIVEN the repository as git tracks it,
+# WHEN  the apex ingress chain, the dashboard's declared link set, every in-repo HTTPRoute,
+#       every hostname-publishing L4 Service, the versioned catalog, the platform-health
+#       alert rules and the console's RBAC posture are read and compared,
+# THEN — R-C2-01 —
+#       (0)  the INPUT SURFACE is intact: every Flux-reconciled path lies inside the roots
+#            this check scans, and every manifest in them parses. A root this check does not
+#            scan, or a file it cannot parse, is a service it cannot see — which would
+#            silently weaken every assertion below;
+#       (1)  EXACTLY ONE HTTPRoute claims the bare apex (an ambiguous root is not a root),
+#            and it belongs to the landing-dashboard component;
+#       (2)  that route pins by sectionName the ONE Gateway listener whose hostname is the
+#            bare apex, and that listener is HTTPS — the wildcard `*.${BASE_DOMAIN}` listener
+#            does NOT intersect the bare apex, so without the sectionName the root binds
+#            nothing and serves nothing (asserted against the wildcard listener's existence,
+#            so the claim is proven rather than asserted from prose);
+#       (3)  the apex is a SAN on the Certificate whose Secret that listener terminates with;
+#       (4)  the dashboard is RECONCILED, not merely authored: one Flux Kustomization points
+#            at its path and is listed in the base entrypoint set;
+#       (5)  that Kustomization carries postBuild.substituteFrom, because the dashboard's
+#            hrefs and its route's hostname are written as `${BASE_DOMAIN}` tokens — without
+#            substitution the apex route binds a literal `${BASE_DOMAIN}` and EVERY tile on
+#            the root links to a nonexistent host, while Flux still reports Ready;
+#       (6)  the component's own kustomization ships config + workload + Service + route;
+#       (7)  the dashboard is a service CATALOG: grouped entries carrying hrefs;
+#       (8)  FORWARD — every home-zone hostname an in-repo HTTPRoute serves, other than the
+#            apex itself, is LINKED from the root. This is the rot-catcher;
+#       (9)  FORWARD — every catalog `kind: container` ServiceDefinition whose declared
+#            ingress host is routed is likewise linked, tying the C2 to the VERSIONED
+#            onboarding contract and not only to whatever is rendered today;
+#       (10) REVERSE — every home-zone link the root offers resolves to something this repo
+#            actually serves: an HTTPRoute (L7) or a hostname-publishing LoadBalancer Service
+#            (L4). A dead tile is a link the root offers to nothing;
+#       (11) the off-cluster escape hatch is not a blanket one: every name declared in the
+#            ConfigMap's `off-cluster-links` annotation is a specific home-zone hostname and
+#            none of them shadows a hostname the repo DOES serve;
+#       (12) no href names a LITERAL base-domain host. Every hostname is the `${BASE_DOMAIN}`
+#            token, so prod's root cannot link dev's services — the 2026-09-04 incident class
+#            (two clusters authored to describe the same names), applied to the front door;
+#     — R-C2-02 —
+#       (13) both health surfaces docs/12 names are linked: the Kubernetes console
+#            (cluster/storage/GitOps state) and the dashboards/alerts surface;
+#       (14) both are RECONCILED by Flux, so the links lead to something running;
+#       (15) the health DATA those surfaces render exists as code — PrometheusRule groups for
+#            each axis R-C2-02 enumerates (cluster/nodes, storage, GitOps reconciliation)
+#            plus certificate expiry — and those rule files are reconciled;
+#       (16) actions are CONTROLLED, not cluster-admin-in-a-browser (docs/12: "never a raw
+#            cluster-admin kubeconfig in a browser"): the console chart is explicitly told NOT
+#            to bind its ServiceAccount to a ClusterRole, so there is no shared privileged
+#            identity to act as;
+#       (17) actions are instead PER-USER: the console is configured for native OIDC with
+#            credentials from a named (SOPS) Secret, not inline;
+#       (18) cluster rights arrive through OIDC GROUPS at MORE THAN ONE privilege level (an
+#            admin group and a lesser one) — least-privilege, not one tier for everybody;
+#       (19) the C2 root DECLARES the authenticated-group posture docs/12 requires, on its own
+#            route (declared, NOT enforced — see the gap note below).
+#
+# WHAT THIS DOES *NOT* PROVE — honest gaps, the same ones the Test declaration names:
+#   - That the apex answers HTTP 200, or that any tile's status ping is green. That is L2; the
+#     Gateway/TLS half is covered under R-DNS-01 / R-TLS-01.
+#   - That the C2 is access-CONTROLLED in fact. (19) reads a DECLARED posture, because the
+#     Gateway ext-authz attachment that would ENFORCE forward-auth is not built anywhere in
+#     this repo (platform/homepage/httproute.yaml says so in its own header, and every
+#     forward-auth app shares the gap). Declared, not enforced, and labelled as such in the
+#     assertion text itself.
+#   - That an operational action in the console succeeds, or that it is audited. (16)-(18)
+#     prove there is no shared cluster-admin identity to act with and that rights arrive
+#     per-user; the audit trail is a runtime property.
+#   - Whether a tile is USEFUL. Homepage service-widget API keys are a deliberate follow-up
+#     (platform/homepage/configmap.yaml); link presence is what R-C2-01 asks for.
+#   - That an L4-ONLY endpoint is surfaced. A raw TCP/UDP endpoint (a Minecraft game port) has
+#     no URL a browser can follow, so the FORWARD direction quantifies over HTTP routes;
+#     L4-published hostnames are listed as ADVISORIES and are honoured in the REVERSE
+#     direction (that is how the UniFi tile, an L4 LoadBalancer on :11443, resolves).
+#   - It does not read ../home-network-k3s. The spec is read-only (R-TEST-06) and the
+#     requirement text above is quoted, not parsed.
+#
+# STATUS: EXECUTABLE. Pure offline: `git ls-files` + PyYAML (the dependency ten neighbouring
+# l0-static checks already take). No cluster, no network, no spec repo.
+# =============================================================================
+set -euo pipefail
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "${DIR}/../../../.." && pwd)"        # repo root
+PYTHON="${PYTHON:-python3}"
+
+# Honest SKIP (never green, and rc 3 is UNWIRED for a scope-declaring test) if the landing
+# dashboard component is absent entirely — there is then no C2 root to audit, which is a
+# report about the tree, not a pass.
+if [ ! -f "${ROOT}/platform/homepage/configmap.yaml" ]; then
+  echo "check SKIPPED: platform/homepage/configmap.yaml absent — no C2 landing dashboard to audit" >&2
+  exit 3
+fi
+
+cd "${ROOT}"
+"${PYTHON}" - "${ROOT}" <<'PY'
+"""Static audit: the C2 root surfaces every service the repository serves, plus health.
+
+Every parse contract is documented at its parser. PyYAML rather than regex because the
+subjects are genuinely structured: multi-document apps/ bundles, and a Homepage config that
+is nested YAML *inside* a ConfigMap string value.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:                                  # pragma: no cover
+    print("check FAIL: PyYAML is required (same dependency as catalog/render.py)",
+          file=sys.stderr)
+    raise SystemExit(1)
+
+ROOT = Path(sys.argv[1])
+sys.dont_write_bytecode = True          # keep __pycache__ out of the tracked tree
+
+FAILURES: list[str] = []
+ADVISORIES: list[str] = []
+CHECKS = 0
+
+
+def check(cond, msg):
+    global CHECKS
+    CHECKS += 1
+    if cond:
+        print(f"  ok   {msg}")
+    else:
+        print(f"  FAIL {msg}", file=sys.stderr)
+        FAILURES.append(msg)
+
+
+def read(p: Path) -> str:
+    try:
+        return p.read_text()
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+# ============================================================ the hostname vocabulary
+# BASE_DOMAIN is a cluster-vars knob (R-ENV-02): every public hostname the cluster serves is
+# `<svc>.${BASE_DOMAIN}`, and dev/prod differ ONLY in that value. So a hostname in this repo
+# is canonically the TOKEN form, and the literal value below exists only to be FORBIDDEN in
+# (12): a literal is how prod came to be authored to serve dev's hostnames (2026-09-04,
+# clusters/base/cluster-vars.yaml's own header).
+TOKEN = "${BASE_DOMAIN}"
+_vars = yaml.safe_load(read(ROOT / "clusters" / "base" / "cluster-vars.yaml")) or {}
+LITERAL_BASE = ((_vars.get("data") or {}).get("BASE_DOMAIN") or "").strip()
+
+
+def strip_port(host: str) -> str:
+    return host.split(":", 1)[0]
+
+
+def zone_label(host: str):
+    """The sub-label of a home-zone hostname, "" for the bare apex, or None if not in zone.
+
+    Accepts only the TOKEN form; a literal-base hostname returns None here and is caught
+    separately by (12), so a literal can never silently satisfy a set comparison.
+    """
+    h = strip_port(host)
+    if h == TOKEN:
+        return ""
+    if h.endswith("." + TOKEN):
+        return h[: -len("." + TOKEN)]
+    return None
+
+
+def is_literal_base(host: str) -> bool:
+    h = strip_port(host)
+    return bool(LITERAL_BASE) and (h == LITERAL_BASE or h.endswith("." + LITERAL_BASE))
+
+
+# ============================================================ (0) the input surface
+# DELIVERY ROOTS — the subtrees Flux reconciles, plus catalog/ (the versioned source the
+# apps/ manifests are rendered FROM). conformance/ is deliberately EXCLUDED: its fixtures and
+# goldens declare synthetic HTTPRoutes (`paas-demo.…`, `gw-declared-conformance.…`) that are
+# test data, not services the cluster serves, and counting them would make (8) assert that
+# the operator's dashboard links this harness's fixtures.
+DELIVERY_ROOTS = ("apps", "platform", "platform-config", "platform-config-cdi",
+                  "runbooks", "clusters", "bootstrap", "catalog")
+
+# NARROW EXEMPTION to (0), for reconciled trees that deliberately serve NOTHING.
+# `conformance/incluster` (the L2/L3 runner + CI-trigger identities, R-SEC-02) is reconciled
+# by clusters/base/conformance.yaml but contains only a Namespace, ServiceAccounts, RBAC and
+# an admission-bounded Job template. Adding "conformance" to DELIVERY_ROOTS instead would be
+# wrong for the reason stated above: it would sweep in this harness's synthetic fixture
+# routes and make (8) demand the operator's dashboard link them.
+#
+# THE EXEMPTION POLICES ITSELF. An unchecked allowlist is how (0) would rot into a fail-open —
+# add a tree here, later put an HTTPRoute in it, and the forward direction goes quietly green
+# on a hidden service. So each exempted tree is ASSERTED below to declare no route and no
+# hostname-publishing Service. If that ever stops being true the check fails and the tree must
+# become a real delivery root.
+NON_SERVING_RECONCILED = ("conformance/incluster",)
+
+
+def tracked_yaml() -> list[Path]:
+    out = subprocess.run(["git", "ls-files", "-z", "--", "*.yaml", "*.yml"],
+                         cwd=ROOT, capture_output=True, text=True, check=True)
+    return [ROOT / p for p in out.stdout.split("\0") if p]
+
+
+ALL_TRACKED = tracked_yaml()
+DELIVERY = [p for p in ALL_TRACKED
+            if p.relative_to(ROOT).parts[0] in DELIVERY_ROOTS]
+
+parse_failed: list[str] = []
+DOCS: dict[Path, list[dict]] = {}
+for p in DELIVERY:
+    try:
+        DOCS[p] = [d for d in yaml.safe_load_all(read(p)) if isinstance(d, dict)]
+    except yaml.YAMLError:
+        DOCS[p] = []
+        parse_failed.append(str(p.relative_to(ROOT)))
+
+
+def docs_all():
+    for p, ds in DOCS.items():
+        for d in ds:
+            yield p, d
+
+
+check(len(DELIVERY) >= 100,
+      f"(0) the delivery tree is present and scanned ({len(DELIVERY)} tracked manifest(s) "
+      f"under {'/, '.join(DELIVERY_ROOTS)}/)")
+check(not parse_failed,
+      f"(0) every manifest in the scanned roots PARSES — an unparseable one is a service "
+      f"this check cannot see, so it would weaken every set comparison below "
+      f"{parse_failed if parse_failed else ''}")
+
+# Every Flux-reconciled path must lie inside a root this check scans. This is the guard on
+# the guard: if a future tier reconciles, say, ./services, the forward direction would stop
+# seeing its routes and would go quietly green on a dashboard that hides all of them.
+flux_ks = [(p, d) for p, d in docs_all()
+           if d.get("kind") == "Kustomization"
+           and str(d.get("apiVersion", "")).startswith("kustomize.toolkit.fluxcd.io")]
+# A RECONCILING Kustomization is one carrying a sourceRef. The pathless documents under
+# bootstrap/flux/patches/ are strategic-merge PATCH FRAGMENTS (they add a decryption stanza to
+# a Kustomization declared elsewhere); they name no source and reconcile nothing, so requiring
+# a path of them would fail on a file that is correct.
+reconcilers = [(p, d) for p, d in flux_ks if (d.get("spec", {}) or {}).get("sourceRef")]
+def _reconciled_path(d):
+    return (d.get("spec", {}) or {}).get("path", "").lstrip("./").rstrip("/")
+
+
+unscanned = sorted({
+    f"{p.relative_to(ROOT)}:{(d.get('spec', {}) or {}).get('path', '') or '(no path)'}"
+    for p, d in reconcilers
+    if _reconciled_path(d).split("/")[0] not in DELIVERY_ROOTS
+    and _reconciled_path(d) not in NON_SERVING_RECONCILED
+})
+
+# The exemption's own guard: an exempted tree must actually serve nothing.
+exempt_serving = sorted({
+    f"{p.relative_to(ROOT)} ({d.get('kind')})"
+    for p, d in docs_all()
+    if any(str(p.relative_to(ROOT)).startswith(t + "/") for t in NON_SERVING_RECONCILED)
+    and (d.get("kind") == "HTTPRoute"
+         or (d.get("kind") == "Service"
+             and any("hostname" in str(k).lower()
+                     for k in ((d.get("metadata", {}) or {}).get("annotations", {}) or {}))))
+})
+check(not exempt_serving,
+      f"(0b) every NON_SERVING_RECONCILED tree really serves nothing — an exempted tree that "
+      f"gains a route would hide a service from this check entirely "
+      f"{exempt_serving if exempt_serving else ''}")
+check(len(reconcilers) >= 10 and not unscanned,
+      f"(0) all {len(reconcilers)} Flux-reconciled path(s) lie inside a scanned root — a "
+      f"reconciled tree this check does not read is a service it cannot require a link for "
+      f"{unscanned if unscanned else ''}")
+
+# ============================================================ what the repo SERVES
+# L7: every hostname an in-repo HTTPRoute claims, and the component that owns it.
+routes: dict[str, list[tuple[Path, dict]]] = {}
+apex_inheriting: list[Path] = []
+for p, d in docs_all():
+    if d.get("kind") != "HTTPRoute":
+        continue
+    hosts = (d.get("spec", {}) or {}).get("hostnames") or []
+    if not hosts:
+        # An HTTPRoute with NO hostnames inherits the hostname of every listener it attaches
+        # to (runbooks/serving/httproute.yaml binds `https-apex` only, so it serves a PATH on
+        # the apex). It introduces no new hostname, so it owes no tile.
+        apex_inheriting.append(p)
+        continue
+    for h in hosts:
+        routes.setdefault(str(h), []).append((p, d))
+
+routed_labels = {}          # sub-label -> owning component dir
+for h, owners in routes.items():
+    lbl = zone_label(h)
+    if lbl:                 # "" is the apex; None is out of zone
+        routed_labels[lbl] = owners[0][0].parent
+
+# L4: a Service that publishes a home-zone hostname to DNS is also "served by this repo" —
+# it is how UniFi (a KubeVirt VM behind a pinned Cilium LoadBalancer VIP on :11443) reaches
+# the LAN. external-dns's annotation IS the declaration; there is no HTTPRoute to find.
+DNS_ANN = "external-dns.alpha.kubernetes.io/hostname"
+l4_labels: dict[str, Path] = {}
+for p, d in docs_all():
+    if d.get("kind") != "Service":
+        continue
+    ann = (d.get("metadata", {}) or {}).get("annotations", {}) or {}
+    for h in re.split(r"[,\s]+", str(ann.get(DNS_ANN, ""))):
+        lbl = zone_label(h) if h else None
+        if lbl:
+            l4_labels[lbl] = p
+
+check(len(routed_labels) >= 10,
+      f"(0) the repo's north-south HTTP surface is discovered "
+      f"({len(routed_labels)} routed home-zone hostname(s), "
+      f"{len(apex_inheriting)} apex-path route(s), {len(l4_labels)} L4-published hostname(s))")
+
+# ============================================================ (1) the apex is unambiguous
+apex_claims = routes.get(TOKEN, [])
+check(len(apex_claims) == 1,
+      f"(1) exactly ONE HTTPRoute claims the bare apex {TOKEN} — an ambiguous root is not a "
+      f"root (found {len(apex_claims)}: {[str(p.relative_to(ROOT)) for p, _ in apex_claims]})")
+apex_path, apex_route = (apex_claims[0] if apex_claims else (None, {}))
+DASH = apex_path.parent if apex_path is not None else None
+check(DASH is not None and DASH.name == "homepage",
+      f"(1) the apex route belongs to the landing-dashboard component "
+      f"(found {DASH.name if DASH else None!r})")
+
+# ============================================================ (2) it binds the apex listener
+parents = (apex_route.get("spec", {}) or {}).get("parentRefs") or []
+section = next((pr.get("sectionName") for pr in parents if pr.get("sectionName")), None)
+gw_name = next((pr.get("name") for pr in parents), None)
+gw_ns = next((pr.get("namespace") for pr in parents), None)
+check(section is not None,
+      "(2) the apex route pins a Gateway listener by sectionName — the wildcard listener's "
+      "hostname cannot match a bare apex, so an unpinned apex route binds NOTHING")
+
+gw = next((d for _, d in docs_all()
+           if d.get("kind") == "Gateway"
+           and (d.get("metadata", {}) or {}).get("name") == gw_name
+           and (gw_ns is None or (d.get("metadata", {}) or {}).get("namespace") == gw_ns)), None)
+check(gw is not None, f"(2) the parent Gateway '{gw_name}' is declared in the repo")
+listeners = ((gw or {}).get("spec", {}) or {}).get("listeners") or []
+apex_listener = next((l for l in listeners if l.get("name") == section), None)
+check(apex_listener is not None,
+      f"(2) the Gateway declares the '{section}' listener the apex route binds")
+check(apex_listener is not None and apex_listener.get("hostname") == TOKEN,
+      f"(2) that listener's hostname is EXACTLY the bare apex "
+      f"(found {(apex_listener or {}).get('hostname')!r})")
+check(apex_listener is not None and apex_listener.get("protocol") == "HTTPS",
+      "(2) the apex listener terminates HTTPS (docs/12 acceptance gate: trusted TLS on the root)")
+# Prove the sectionName is LOAD-BEARING rather than decorative: a wildcard listener exists,
+# it is a DIFFERENT listener, and its hostname does not equal the apex.
+wildcard = [l for l in listeners if str(l.get("hostname", "")) == "*." + TOKEN]
+check(bool(wildcard) and all(l.get("name") != section for l in wildcard),
+      f"(2) the wildcard listener(s) {[l.get('name') for l in wildcard]} are DISTINCT from "
+      f"'{section}' — which is why the apex needs its own listener, and why dropping the "
+      f"sectionName would leave the root unserved")
+
+# ============================================================ (3) trusted TLS on the root
+cert_secret = next((ref.get("name")
+                    for ref in ((apex_listener or {}).get("tls", {}) or {}).get("certificateRefs") or []),
+                   None)
+cert = next((d for _, d in docs_all()
+             if d.get("kind") == "Certificate"
+             and (d.get("spec", {}) or {}).get("secretName") == cert_secret), None)
+check(cert is not None,
+      f"(3) a cert-manager Certificate produces the apex listener's Secret ({cert_secret!r})")
+check(cert is not None and TOKEN in ((cert.get("spec", {}) or {}).get("dnsNames") or []),
+      "(3) the bare apex is a SAN on that Certificate — the wildcard alone does NOT cover it, "
+      "so without this SAN the root serves an untrusted certificate")
+
+# ============================================================ (4)(5) it is RECONCILED
+dash_rel = f"./{DASH.relative_to(ROOT)}" if DASH else None
+dash_ks = [(p, d) for p, d in flux_ks
+           if (d.get("spec", {}) or {}).get("path", "").rstrip("/") == dash_rel]
+check(len(dash_ks) == 1,
+      f"(4) exactly one Flux Kustomization reconciles the dashboard ({dash_rel}) — authored "
+      f"but unreconciled is the 'looks done, is absent' class this repo keeps hitting "
+      f"(found {len(dash_ks)})")
+if dash_ks:
+    base_txt = read(ROOT / "clusters" / "base" / "kustomization.yaml")
+    entry = dash_ks[0][0].name
+    check(re.search(rf"^\s*-\s*{re.escape(entry)}\s*(#.*)?$", base_txt, re.M) is not None,
+          f"(4) that Kustomization is listed in the base entrypoint set ({entry})")
+    # (5) The dashboard's hrefs and its route's hostname are ${BASE_DOMAIN} TOKENS. Without
+    # postBuild.substituteFrom the token reaches the cluster LITERALLY: the apex route binds
+    # the host `${BASE_DOMAIN}` (matching no listener) and every tile links to a host that
+    # does not exist — and Flux still reports the Kustomization Ready. It fails OPEN.
+    subs = (((dash_ks[0][1].get("spec", {}) or {}).get("postBuild") or {}).get("substituteFrom") or [])
+    check(any((s.get("name") == "cluster-vars") for s in subs),
+          f"(5) {dash_ks[0][0].name} carries postBuild.substituteFrom cluster-vars. It MUST: "
+          f"this component's route hostname and EVERY tile href are ${{BASE_DOMAIN}} tokens, "
+          f"and an unsubstituted token is applied literally while Flux still reports Ready — "
+          f"a root bound to no listener and a dashboard of dead links, with a green tier")
+
+# ============================================================ (6) it ships the UI
+dash_kust = yaml.safe_load(read(DASH / "kustomization.yaml")) if DASH else None
+dash_res = set((dash_kust or {}).get("resources") or [])
+for want in ("configmap.yaml", "deployment.yaml", "service.yaml", "httproute.yaml"):
+    check(want in dash_res, f"(6) the dashboard kustomization ships {want}")
+
+# ================================================== the dashboard's DECLARED link set
+# Homepage's config is nested YAML inside ConfigMap string values (services.yaml,
+# bookmarks.yaml). Both are read: a bookmark is a link the root offers just as a tile is.
+cm = next((d for d in (DOCS.get(DASH / "configmap.yaml") or []) if d.get("kind") == "ConfigMap"),
+          {}) if DASH else {}
+cm_data = cm.get("data") or {}
+
+
+def embedded(key):
+    try:
+        return yaml.safe_load(cm_data.get(key) or "") or []
+    except yaml.YAMLError:
+        return None
+
+
+svc_cfg = embedded("services.yaml")
+bm_cfg = embedded("bookmarks.yaml")
+check(svc_cfg is not None and bm_cfg is not None,
+      "(7) the dashboard's embedded services.yaml / bookmarks.yaml parse as YAML — the app "
+      "mounts these verbatim, so a malformed one is a dashboard that renders nothing")
+
+
+def hrefs(node):
+    """Every href anywhere in Homepage's nested group/entry structure."""
+    if isinstance(node, dict):
+        for k, v in node.items():
+            if k == "href" and isinstance(v, str):
+                yield v
+            else:
+                yield from hrefs(v)
+    elif isinstance(node, list):
+        for v in node:
+            yield from hrefs(v)
+
+
+def host_of(url):
+    m = re.match(r"^https?://([^/]+)", url or "")
+    return m.group(1) if m else None
+
+
+tile_urls = list(hrefs(svc_cfg or []))
+all_urls = tile_urls + list(hrefs(bm_cfg or []))
+all_hosts = [h for h in (host_of(u) for u in all_urls) if h]
+linked = {lbl for lbl in (zone_label(h) for h in all_hosts) if lbl}
+tile_labels = {lbl for lbl in (zone_label(h) for h in (host_of(u) for u in tile_urls) if h) if lbl}
+
+groups = [g for g in (svc_cfg or []) if isinstance(g, dict)]
+check(len(groups) >= 1 and len(tile_labels) >= 5,
+      f"(7) the root is a grouped service catalog with links "
+      f"({len(groups)} group(s), {len(tile_labels)} linked home-zone service(s))")
+
+# ============================================ (8) FORWARD: nothing routed is hidden
+unsurfaced = sorted(set(routed_labels) - linked)
+check(not unsurfaced,
+      "(8) every service the repo ROUTES over HTTP is surfaced on the C2 root. Unsurfaced: "
+      + ", ".join(f"{n}.{TOKEN} ({routed_labels[n].relative_to(ROOT)})" for n in unsurfaced)
+      if unsurfaced else
+      f"(8) every service the repo ROUTES over HTTP is surfaced on the C2 root "
+      f"({len(routed_labels)} hostname(s) compared)")
+
+# L4-only endpoints are reported, never required: a raw TCP/UDP port has no browsable URL.
+for lbl in sorted(set(l4_labels) - linked):
+    ADVISORIES.append(
+        f"{lbl}.{TOKEN} is published to DNS by an L4 Service "
+        f"({l4_labels[lbl].relative_to(ROOT)}) and is not linked from the root. Not a "
+        f"failure: a raw TCP/UDP endpoint has no URL a browser can follow. Verify the "
+        f"service it belongs to is reachable through a tile that IS linked")
+
+# ================================= (9) FORWARD: the VERSIONED onboarding contract
+cat_dir = ROOT / "catalog"
+cat_seen, cat_missing, cat_unrouted = 0, [], []
+for p in sorted(cat_dir.glob("*.yaml")):
+    sd = next((d for d in (DOCS.get(p) or [])), None)
+    if not isinstance(sd, dict) or sd.get("kind") != "container":
+        continue                      # kind: vm has no north-south HTTP surface (docs/09)
+    for r in sd.get("ingressRoutes") or []:
+        lbl = zone_label(str(r.get("host", "")))
+        if not lbl:
+            continue
+        if lbl not in routed_labels:
+            # Declared in the catalog but not rendered into a route: an apps/ render drift
+            # problem owned by R-GITOPS-02, reported here rather than silently skipped.
+            cat_unrouted.append(f"{sd.get('name')}:{lbl}")
+            continue
+        cat_seen += 1
+        if lbl not in linked:
+            cat_missing.append(f"{sd.get('name')}:{lbl}")
+check(cat_seen >= 5,
+      f"(9) the versioned catalog contributes routed HTTP services ({cat_seen} found) — the "
+      f"C2 is tied to the onboarding contract, not only to today's rendered output")
+check(not cat_missing,
+      f"(9) every catalog `kind: container` service with a route is linked from the C2 root "
+      f"{cat_missing if cat_missing else ''}")
+for u in cat_unrouted:
+    ADVISORIES.append(f"catalog declares an ingress host with no rendered HTTPRoute: {u} "
+                      f"(render drift — R-GITOPS-02 owns it, not R-C2-01)")
+
+# ============================ (10)(11) REVERSE: no link points at nothing
+ann = (cm.get("metadata", {}) or {}).get("annotations", {}) or {}
+OFF_ANN = "homelab.keithjackson.dev/off-cluster-links"
+declared_off_raw = [t for t in re.split(r"[,\s]+", str(ann.get(OFF_ANN, ""))) if t]
+declared_off = {zone_label(t) for t in declared_off_raw}
+served = set(routed_labels) | set(l4_labels)
+dead = sorted(linked - served - declared_off)
+check(not dead,
+      f"(10) every home-zone link the root offers resolves to something this repo serves — "
+      f"an HTTPRoute (L7) or a hostname-publishing LoadBalancer Service (L4). Dead: "
+      f"{[f'{d}.{TOKEN}' for d in dead] if dead else ''}")
+# The escape hatch is a DECLARATION, not a hole: same doctrine as an explicit `NONE` in
+# ci/touched-requirements.sh's path map. Empty today, and these two hold vacuously when it is
+# — they exist so it cannot be widened into a blanket without failing.
+check(all(zone_label(t) for t in declared_off_raw),
+      f"(11) every declared off-cluster link is a specific home-zone hostname in TOKEN form "
+      f"({declared_off_raw})")
+shadowed = sorted(declared_off & served)
+check(not shadowed,
+      f"(11) no off-cluster declaration shadows a hostname the repo DOES serve "
+      f"{shadowed if shadowed else ''}")
+
+# ============================ (12) tokens, never literals
+literal_hosts = sorted({h for h in all_hosts if is_literal_base(h)})
+check(not literal_hosts,
+      f"(12) no link on the root names a LITERAL '{LITERAL_BASE}' host — every hostname is the "
+      f"${{BASE_DOMAIN}} token, so prod's front door cannot link dev's services (the "
+      f"2026-09-04 class: two clusters authored to describe the same names). Literals: "
+      f"{literal_hosts if literal_hosts else ''}")
+
+# =====================================================================
+# R-C2-02 — platform health, and controlled operational actions
+# =====================================================================
+# docs/12 names the surfaces the C2 composes: Headlamp is "the R-C2-02 'controlled
+# operational actions where safe' surface"; Grafana is the dashboards/alerts surface. Each is
+# identified by the component that OWNS ITS ROUTE, not by a magic string in the config.
+CONSOLE, DASHBOARDS = "headlamp", "grafana"
+check(CONSOLE in linked,
+      f"(13) the C2 root links the Kubernetes console ({CONSOLE}.{TOKEN}) — cluster, storage "
+      f"and GitOps state, and the R-C2-02 operational-actions surface (docs/12)")
+check(DASHBOARDS in linked,
+      f"(13) the C2 root links the dashboards/alerts surface ({DASHBOARDS}.{TOKEN})")
+
+AGG = ("\n".join(read(ROOT / t / "kustomization.yaml")
+                 for t in ("platform", "platform-config", "platform-config-cdi")))
+for label, name in (("console", CONSOLE), ("dashboards", DASHBOARDS)):
+    comp = routed_labels.get(name)
+    check(comp is not None, f"(14) the {label} surface has an in-repo HTTPRoute")
+    if comp is None:
+        continue
+    rel = f"./{comp.relative_to(ROOT)}"
+    reconciled = any((d.get("spec", {}) or {}).get("path", "").rstrip("/") == rel
+                     for _, d in flux_ks)
+    if not reconciled:
+        # A component may reconcile as a MEMBER of an aggregate tier's kustomize tree
+        # (platform / platform-config) instead of owning a Flux Kustomization. Both count;
+        # being in NEITHER is "authored, never applied".
+        reconciled = (f"\n  - {comp.name}" in AGG
+                      or f"../{comp.relative_to(ROOT)}/" in AGG)
+    check(reconciled,
+          f"(14) the {label} surface ({comp.name}) is reconciled by Flux, not merely authored "
+          f"— a link to an unreconciled component is a link to nothing")
+
+# (15) the health DATA exists as code, for every axis R-C2-02 enumerates.
+rule_files = sorted({p for p, d in docs_all() if d.get("kind") == "PrometheusRule"})
+rule_groups = {g.get("name", "")
+               for p, d in docs_all() if d.get("kind") == "PrometheusRule"
+               for g in ((d.get("spec", {}) or {}).get("groups") or [])}
+for axis, needle in (("cluster/nodes", "nodes"),
+                     ("storage", "longhorn"),
+                     ("GitOps reconciliation", "flux"),
+                     ("certificate expiry", "certificates")):
+    check(any(needle in g for g in rule_groups),
+          f"(15) platform-health alert rules exist for {axis} (a '*{needle}*' rule group) — "
+          f"the C2 cannot surface health that is not measured")
+pc_txt = read(ROOT / "platform-config" / "kustomization.yaml")
+reconciled_rules = [p for p in rule_files if f"../{p.relative_to(ROOT)}" in pc_txt]
+check(len(reconciled_rules) >= 2,
+      f"(15) those alert rules are RECONCILED — PrometheusRule is a CR of a CRD the platform "
+      f"tier installs, so the rules are applied by platform-config "
+      f"({len(reconciled_rules)}/{len(rule_files)} rule file(s) referenced there)")
+
+# (16)(17) controlled actions: no shared cluster-admin identity; per-user OIDC instead.
+console_dir = routed_labels.get(CONSOLE)
+hr = next((d for p in (sorted(console_dir.glob("*.yaml")) if console_dir else [])
+           for d in (DOCS.get(p) or []) if d.get("kind") == "HelmRelease"), None)
+check(hr is not None, "(16) the Kubernetes console is deployed by a HelmRelease")
+hv = ((hr or {}).get("spec", {}) or {}).get("values", {}) or {}
+check((hv.get("clusterRoleBinding") or {}).get("create") is False,
+      "(16) the console chart is told NOT to bind its ServiceAccount to a ClusterRole. The "
+      "chart's DEFAULT binds it to cluster-admin, which is exactly the 'raw cluster-admin "
+      "kubeconfig in a browser' docs/12 forbids — every visitor would act as one shared "
+      "omnipotent identity")
+oidc = ((hv.get("config") or {}).get("oidc") or {})
+check(bool(oidc),
+      "(17) the console is configured for native OIDC login, so an action carries the "
+      "operator's OWN identity (docs/12: Headlamp/Grafana use native OIDC)")
+check(bool((oidc.get("externalSecret") or {}).get("name")),
+      "(17) its OIDC client credentials come from a NAMED (SOPS) Secret, not inline in the "
+      "HelmRelease values — R-SEC-01")
+
+# (18) rights arrive through GROUPS, at more than one privilege level.
+group_bindings = []
+for p, d in docs_all():
+    if d.get("kind") not in ("ClusterRoleBinding", "RoleBinding"):
+        continue
+    for s in d.get("subjects") or []:
+        if s.get("kind") == "Group" and str(s.get("name", "")).startswith("oidc:"):
+            group_bindings.append(((d.get("metadata", {}) or {}).get("name"),
+                                   s.get("name"),
+                                   (d.get("roleRef") or {}).get("name")))
+check(len(group_bindings) >= 2,
+      f"(18) cluster rights are bound to OIDC GROUPS, so access follows Keycloak group "
+      f"membership rather than a per-user grant somebody must remember to revoke "
+      f"({[(g, r) for _, g, r in group_bindings]})")
+check(any(r == "cluster-admin" for _, _, r in group_bindings)
+      and any(r != "cluster-admin" for _, _, r in group_bindings),
+      "(18) MORE THAN ONE privilege level exists (an admin group AND a lesser one) — "
+      "least-privilege, not one tier for everybody (docs/12 access control, R-IDP-06)")
+
+# (19) the root DECLARES the authenticated-group posture. DECLARED, NOT ENFORCED.
+route_ann = (apex_route.get("metadata", {}) or {}).get("annotations", {}) or {}
+check(route_ann.get("homelab.keithjackson.dev/auth-mode") in ("forward-auth", "oidc", "oauth2-proxy"),
+      f"(19) the C2 root's route DECLARES an authentication mode "
+      f"(found {route_ann.get('homelab.keithjackson.dev/auth-mode')!r}) "
+      f"[DECLARED, NOT ENFORCED — no Gateway ext-authz attachment exists in this repo]")
+check(bool(route_ann.get("homelab.keithjackson.dev/auth-groups")),
+      "(19) it DECLARES the authorized group(s) — docs/12 requires an authenticated user IN "
+      "AN AUTHORIZED GROUP, not merely logged in "
+      "[DECLARED, NOT ENFORCED — see the header's gap note]")
+
+# ======================================================================== report
+print()
+print(f"C2 surface inventory (apex {TOKEN}, literal base default '{LITERAL_BASE}'):")
+print(f"  routed over HTTP : {len(routed_labels)}  -> {', '.join(sorted(routed_labels))}")
+print(f"  L4-published     : {len(l4_labels)}  -> {', '.join(sorted(l4_labels)) or '(none)'}")
+print(f"  linked from root : {len(linked)}  -> {', '.join(sorted(linked))}")
+print(f"  apex-path routes : {len(apex_inheriting)}  -> "
+      f"{', '.join(str(p.relative_to(ROOT)) for p in apex_inheriting) or '(none)'}")
+print(f"  catalog services compared: {cat_seen}   off-cluster declarations: "
+      f"{sorted(declared_off_raw) or '(none)'}")
+
+if ADVISORIES:
+    print("\nADVISORIES (not failures):")
+    for a in ADVISORIES:
+        print(f"  - {a}")
+
+print()
+if not FAILURES:
+    print(f"check OK: c2-root-surface — {CHECKS} assertions (R-C2-01, R-C2-02)")
+    raise SystemExit(0)
+print(f"CHECK FAIL (c2-root-surface): {len(FAILURES)} failed, "
+      f"{CHECKS - len(FAILURES)} passed", file=sys.stderr)
+for f in FAILURES:
+    print(f"  FAIL {f}", file=sys.stderr)
+raise SystemExit(1)
+PY
@@ -57,6 +57,14 @@ metadata:
  annotations:
    conformance.home.k3s/requirements: "R-ENV-01"
    conformance.home.k3s/layer: "L0"
+    # NO `scope` ANNOTATION, DELIBERATELY — this invariant IS path-scoped, and was audited as
+    # such (2026-09-12). Its entire input surface is infra/ (OpenTofu + the Ansible roles that
+    # provision the dev nodes); it reads nothing else. The gap was that
+    # ci/touched-requirements.sh keyed infra/* to NOTHING, so an infra/ edit attributed no
+    # requirement and this check was filtered out. The right fix for a path-scoped invariant is
+    # a path-map entry, not an unconditional run: `infra/*) echo "R-ENV-01"` was added there in
+    # the same change. Keep the two in sync — if this check ever grows an assertion outside
+    # infra/, either widen that map entry or give this test a whole-repo scope.
    conformance.home.k3s/safety-critical: "false"
    conformance.home.k3s/executable: "true"
    conformance.home.k3s/intent: >-
@@ -74,6 +74,11 @@ metadata:
  annotations:
    conformance.home.k3s/requirements: "R-NET-04"
    conformance.home.k3s/layer: "L0"
+    # WHOLE-REPO SCOPE. Universally quantified over tracked YAML: every manifest that carries
+    # an egress-class label/annotation must use a value the policy set actually steers. The
+    # file most likely to break it is a NEW workload under apps/ — which attributes no
+    # requirement — not platform/vpn-egress/ (the only path the map keys to R-NET-04).
+    conformance.home.k3s/scope: "whole-repo"
    conformance.home.k3s/safety-critical: "false"
    conformance.home.k3s/executable: "true"
    conformance.home.k3s/intent: >-
@@ -8,6 +8,18 @@
 # the empty string while the Kustomization still reports Ready — which emptied Cilium's
 # k8sServiceHost and broke the CNI on 2/3 dev nodes (DECISIONS-LOG 2026-09-01).
 #
+# It is also LOSSY IN THE OTHER DIRECTION, and that is the second incident on this record.
+# envsubst consumes dollars in PAIRS and emits one per pair, unconditionally and everywhere —
+# so no substituted path can carry a literal `$$` at all. On 2026-09-13 a ConfigMap under
+# apps-wave-0 shipped a dollar-quoted PL/pgSQL `DO $$ ... $$;` self-check; Postgres received
+# a half-quoted `DO $` and every Flux-reconciled run of the nextcloud-db grant reconciler died
+# with a syntax error, nine Error pods deep before anyone looked (commit 16b7fcd). It passed
+# review because it was hand-applied with `kubectl apply`, which runs no envsubst: the defect
+# existed ONLY on the rendered path, and it landed on the assertion whose whole job was to
+# make a silent regression visible. Nothing here failed — the manifest rendered
+# "successfully" into something broken, because the check treated any doubled dollar as a
+# deliberate escape and stopped looking.
+#
 # GIVEN every Flux Kustomization under clusters/ that declares postBuild.substituteFrom,
 # WHEN  each `spec.path` is resolved to the exact file set it renders (following
 #       kustomization.yaml `resources:` transitively, not globbing the repo),
@@ -15,7 +27,12 @@
 #       or deliberately ESCAPED `$${...}`; no unescaped expansion carries a default
 #       operator on an undefined name (the silent-empty class strict mode does NOT catch);
 #       no unescaped expansion is unparseable by envsubst (which fails the WHOLE
-#       Kustomization); every path rendering a knob actually substitutes cluster-vars;
+#       Kustomization); NO RUN OF TWO OR MORE DOLLARS IS SILENTLY REWRITTEN — the only shape
+#       that passes unremarked is exactly `$${`, the documented total escape, and every other
+#       run (a bare `$$` that cannot survive verbatim, an ODD `$$${...}` that only LOOKS
+#       escaped and in fact expands, an over-counted `$$$${...}`) is named and justified in
+#       `dollar-collapse.allow`, which is itself held to being exact and non-stale;
+#       every path rendering a knob actually substitutes cluster-vars;
 #       every overlay-patched knob has a base default; and the check is wired into the
 #       merge gate as a blocking, unconditionally-run stage.
 #
@@ -26,6 +43,19 @@
 # only); conformance/run.sh --layer l0 and ci/l0.sh run it directly, and this Chainsaw
 # Test wraps the SAME script.
 #
+# NOT proven, and deliberately NOT proxied: the wider lesson of 2026-09-13 is that the bug
+# survived review because verification used a path (`kubectl apply`) that runs no
+# substitution. That property is NOT statically decidable from this repo — which command
+# someone ran is a fact about a shell session, and git stores the manifest, never the
+# invocation. Grepping commit prose or runbooks for `kubectl apply` would be trivially
+# satisfiable by rewording and would fire on the break-glass runbooks whose whole content is
+# that command, so no such proxy is attempted. The dollar-run assertion is the honest answer
+# instead: it moves the proof off the verification PATH and onto the SOURCE, where it IS
+# decidable, so the mangling is caught by reading the manifest however a human chose to try
+# it. An end-to-end `kustomize build | flux envsubst --strict` per substituted path would be
+# the real thing, and it is how the arithmetic in check.sh's header was measured — but the L0
+# CI toolchain installs neither tool, so as a gate stage it would SKIP permanently.
+#
 # NOT proven (named in check.sh's header): this is a STATIC scan of the SOURCE manifests
 # a path includes — a deliberate superset of the post-`kustomize build` stream. It does
 # not render, does not prove the feature gate is enabled on the live kustomize-controller,
@@ -43,18 +73,36 @@ metadata:
  annotations:
    conformance.home.k3s/requirements: "R-ENV-02, R-GITOPS-01"
    conformance.home.k3s/layer: "L0"
+    # WHOLE-REPO SCOPE — relocated verbatim from ci/l0.sh's hand-written "Stage 3c
+    # (UNCONDITIONAL)", which this annotation replaces:
+    #
+    #   R-ENV-02's promote-once mechanism is `postBuild.substituteFrom cluster-vars`, and it
+    #   FAILS OPEN: an undefined ${TOKEN} becomes the empty string and the Kustomization still
+    #   reports Ready. That emptied Cilium's k8sServiceHost and broke the CNI on 2/3 dev nodes
+    #   (DECISIONS-LOG 2026-09-01, "substitution race that fails OPEN").
+    #
+    #   WHY IT MUST NOT BE REQUIREMENT-SCOPED: ci/touched-requirements.sh's coarse path map
+    #   keys only clusters/* to R-ENV-02 — an edit to a SUBSTITUTED manifest under apps/ or
+    #   platform/ attributes no requirement, so the requirement-scoped selection would filter
+    #   this check out of exactly the change that introduces the bug. The invariant spans every
+    #   path any Flux Kustomization substitutes (apps/, platform/, platform-config/), so it runs
+    #   on EVERY gate invocation.
+    conformance.home.k3s/scope: "whole-repo"
    conformance.home.k3s/safety-critical: "false"
    conformance.home.k3s/executable: "true"
    conformance.home.k3s/intent: >-
      Every variable a substituted Flux path renders is defined in cluster-vars or
      escaped, so post-build substitution cannot silently empty a value and enabling
-      StrictPostBuildSubstitutions cannot fail a legitimate manifest.
+      StrictPostBuildSubstitutions cannot fail a legitimate manifest; and no dollar run
+      envsubst rewrites reaches the cluster unreviewed, so content that must arrive
+      verbatim cannot be silently mangled on the Flux-rendered path (16b7fcd).
 spec:
  steps:
    - name: audit-every-substituted-flux-path
      description: >-
        Resolve each postBuild.substituteFrom Kustomization to the files it renders and
-        assert every ${...} is defined or escaped, then assert the gate wires it blocking.
+        assert every ${...} is defined or escaped and no dollar run is silently collapsed,
+        then assert the gate wires it blocking.
      try:
        - script:
            content: bash ./check.sh
@@ -18,6 +18,32 @@
 # substituted path renders is either DEFINED or deliberately ESCAPED — and nothing in
 # the repo asserted that. This check does.
 #
+# SECOND INCIDENT, 2026-09-13 — THE INVERSE HAZARD (commit 16b7fcd)
+# ------------------------------------------------------------------
+# The first incident was a variable the author wanted EXPANDED that rendered EMPTY. This one
+# is its mirror: content the author wanted to reach the workload UNTOUCHED that substitution
+# silently REWROTE. A CronJob reconciler in apps/wave-0/nextcloud-db.yaml asserted its own
+# convergence in a dollar-quoted PL/pgSQL block —
+#
+#     DO <dq> BEGIN ... END <dq>;     where <dq> is two literal dollars: standard Postgres
+#
+# — inside a ConfigMap under apps-wave-0, which declares postBuild.substituteFrom. envsubst
+# collapses a doubled dollar into ONE dollar, ALWAYS, so Postgres received a half-quoted
+# `DO <one dollar>` and died with `syntax error at or near "$"`. Three scheduled runs left
+# nine Error pods in nextcloud-db before anyone looked.
+#
+# It PASSED verification because it was hand-applied with `kubectl apply`, which runs NO
+# envsubst. The defect existed ONLY on the Flux-rendered path. And the damage landed
+# precisely on the self-check: the GRANT on line 1 still ran, so the privilege stayed
+# correct and the only thing broken was the assertion meant to make a silent regression
+# visible — the part whose whole job is to stop a blind spot being quiet.
+#
+# THE ASSERTION GAP THIS CLOSES: assertions (1)-(3) below ask whether every `${...}` is
+# defined, escaped, or parseable. They said NOTHING about a doubled dollar that is not an
+# escape, because the old classifier treated a `$` run of length >= 2 as "escaped, therefore
+# fine" and stopped looking. Nothing failed the gate; the manifest rendered "successfully"
+# into something broken. Assertion (7) is that hole, closed.
+#
 # ENVSUBST BEHAVIOUR ASSERTED HERE (empirically verified against the pinned toolchain,
 # `flux envsubst`, flux 2.4.0 — this is measured behaviour, not assumption):
 #   ${DEFINED}        -> substituted with the cluster-vars value.
@@ -33,6 +59,66 @@
 #                        shell/cloud-init consumer. Escaping is total: it neutralises
 #                        even the indexed form.
 #   $VAR, $(cmd)      -> left alone by envsubst; they need no escaping.
+#
+# DOLLAR-RUN ARITHMETIC — the exact rule, MEASURED, not inferred (see assertion (7))
+# ---------------------------------------------------------------------------------
+# envsubst here is `github.com/fluxcd/pkg/envsubst` v1.1.0 — Flux's own maintained FORK of
+# `github.com/drone/envsubst` ("This package is a fork of drone/envsubst", its README) — and it
+# is exposed by the `flux envsubst` CLI ("replicate the behavior of the Flux Kustomization
+# post-build substitutions", its own --help). Named from the binary, not from memory: the
+# pinned flux 2.4.0 in the dev image embeds the Go module path
+# `/home/runner/go/pkg/mod/github.com/fluxcd/pkg/[email protected]/parse`
+# (`grep -ao 'github.com/fluxcd/pkg/envsubst[^ ]*' "$(command -v flux)"`). Its scanner walks
+# the input left to right; on a `$` it looks at the NEXT byte:
+#   * another `$`   -> BOTH are consumed and ONE `$` is emitted. This is UNCONDITIONAL. What
+#                      follows the pair is irrelevant — `{`, a letter, a digit, a semicolon,
+#                      a newline, end of input. `$$` is not "the escape for `${`"; it is the
+#                      escape for `$` itself, everywhere.
+#   * `{`           -> the braced expression is parsed and EXPANDED.
+#   * anything else -> the `$` is emitted literally (hence `$VAR` and `$(cmd)` survive).
+# So a run of N consecutive dollars emits floor(N/2) literal dollars, and when N is ODD the
+# final dollar is still LIVE. Measured with flux 2.4.0 `flux envsubst`, DEFINED=VALUE — the
+# left column is authored bytes, the right is what reaches the cluster:
+#
+#   $                 ->  $                  ${DEFINED}       ->  VALUE
+#   $$                ->  $                  $${DEFINED}      ->  ${DEFINED}   <- the escape
+#   $$$               ->  $$                 $$${DEFINED}     ->  $VALUE   <- ODD: brace LIVE
+#   $$$$              ->  $$                 $$$${DEFINED}    ->  $${DEFINED}
+#   $$$$$             ->  $$$                $$$$${DEFINED}   ->  $$VALUE
+#   DO $$ .. $$;      ->  DO $ .. $;         $$${NOPE:-d}     ->  $d
+#   awk '{print $$2}' ->  awk '{print $2}'   $${ARR[0]}       ->  ${ARR[0]}    (safe)
+#   $$@ $$< $$^       ->  $@ $< $^           $$${ARR[0]}      ->  HARD PARSE ERROR, whole
+#                                                                 Kustomization dies
+#
+# TWO CONSEQUENCES THIS CHECK IS BUILT ON:
+#   (a) THERE IS NO WAY TO SHIP A LITERAL `$$` THROUGH A SUBSTITUTED PATH. To make two
+#       dollars arrive you must author FOUR. So any authored `$$` that is meant to reach the
+#       workload verbatim is a BUG, full stop — that is the 2026-09-13 incident, and Postgres
+#       dollar-quoting is its commonest shape (Makefile `$$@`, awk `$$2` and docker-compose
+#       `$${}` are the same hazard arriving from the other direction: there the collapse is
+#       what the author wanted).
+#   (b) `$$$` + brace is NOT "more escaped" than `$$` + brace — it is NOT escaped at all. An
+#       odd run leaves one live dollar, so the brace expands, or, for an inner envsubst
+#       cannot parse, fails the ENTIRE Kustomization (proven above with $$${ARR[0]}, which
+#       aborted the whole stream while $${ARR[0]} on the line before it was fine).
+# `--strict` reports NONE of this: every row of that table except the parse error was
+# accepted SILENTLY by `flux envsubst --strict`, exit 0, and its output was BYTE-IDENTICAL to
+# non-strict (`cmp`). Strict mode cannot see this class, so a source-level assertion is the
+# only available guard.
+#
+# TO REPRODUCE THE TABLE (30 seconds, no cluster) — it is a measurement, so re-measure it
+# after any FLUX_VERSION bump in infra/devcontainer/versions.env. Open the toolbox with
+# `./infra/devcontainer/dev.sh` and run these INSIDE it (do NOT pipe into `dev.sh run` from
+# the host: it starts the container with `-it`, so a piped stdin hangs):
+#   printf '[$$] [$$$] [$${D}] [$$${D}] [DO $$ x $$;]\n' | D=VALUE flux envsubst
+#   -> [$] [$$] [${D}] [$VALUE] [DO $ x $;]
+# And end-to-end, on the actual delivery path, with the pre-16b7fcd manifest checked out
+# (`git show 16b7fcd^:apps/wave-0/nextcloud-db.yaml > apps/wave-0/nextcloud-db.yaml`):
+#   kubectl kustomize apps/wave-0 | grep 'DO \$'            -> "DO $$"  (the kubectl path)
+#   kubectl kustomize apps/wave-0 | flux envsubst --strict | grep 'DO \$'
+#                                                           -> "DO $"   (the FLUX path), exit 0
+# (`kubectl kustomize` IS the kustomize build here; the image ships no standalone binary.)
+# That two-command contrast IS the 2026-09-13 incident, and is why review missed it.
 #   ${...}, ${a b}, ${ARR[0]}  (UNESCAPED) -> HARD PARSE ERROR ("unable to parse
 #                        variable name" / "missing closing brace") which fails the
 #                        WHOLE Kustomization — every resource in the path, not just
@@ -55,7 +141,14 @@
 #       (5) every knob an overlay patches (`/data/KEY`) exists in the BASE ConfigMap —
 #           the "add the knob with a base default BEFORE referencing it" rule that the
 #           incident's interim discipline depends on;
-#   AND (6) this check is LOAD-BEARING: ci/l0.sh runs it on every gate run and
+#       (7) NO DOLLAR RUN IS SILENTLY REWRITTEN: the only run of length >= 2 that passes
+#           unremarked is exactly `$$` immediately followed by `{` — the documented, total,
+#           already-inventoried escape. EVERY other run of >= 2 dollars (a bare `$$`, an odd
+#           `$$$`, an over-counted `$$$$`) is rewritten by envsubst between git and the
+#           container, so it must be named and justified in `dollar-collapse.allow`, a file
+#           this check also holds to being exact and non-stale;
+#   AND (6) this check is LOAD-BEARING: it DECLARES `conformance.home.k3s/scope: whole-repo`,
+#           so ci/l0.sh's `--include-scope whole-repo` runs it on every gate run, and
 #           ci/gate.sh sets the merge block when the l0 stage fails.
 # Assertion (1)-(3) are applied to COMMENTS as well as content: `kustomize build`
 # preserves body comments into the stream envsubst reads (verified: a `$`-carrying
@@ -78,6 +171,21 @@
 #     kustomize-controller. Both are cluster facts (L2), untested here. Tagging
 #     R-GITOPS-01 claims ONLY the static slice: what git says a Kustomization renders
 #     is fully determined, with no variable silently emptied on the way in.
+#   - It CANNOT prove the thing that actually let 16b7fcd's bug reach a cluster: that a
+#     change was VERIFIED through a substituting path. "It was hand-applied with kubectl" is
+#     a fact about a shell session, not about any tracked file — git records the manifest,
+#     never the command someone ran to try it, so the property is not statically decidable
+#     here and no honest formulation of it exists. Nor is a proxy worth having: grepping
+#     commit prose or runbooks for `kubectl apply` would be trivially satisfiable by
+#     rewording, and would fire on the many legitimate break-glass runbooks whose whole
+#     content is that command. So this check does not attempt it, and does not pretend to.
+#     Assertion (7) answers that incident a different way: it moves the proof off the
+#     verification PATH, which is unknowable, and onto the SOURCE, which is not — the
+#     mangling is now caught by reading the manifest, whichever way a human chose to try it.
+#     (The one decidable half-measure, `kustomize build <path> | flux envsubst --strict` per
+#     substituted path in CI, is already ruled out above: the L0 toolchain installs neither
+#     tool, so the stage would SKIP permanently. The dev image has both, and it is how the
+#     arithmetic table above was measured.)
 #   - It does NOT validate cluster-vars VALUES (that GATEWAY_VIP is inside the LB pool,
 #     that an overlay's LAN block is self-consistent). Presence, not correctness.
 #   - A cluster-vars key nothing references is reported as an ADVISORY, never a failure:
@@ -107,6 +215,7 @@ definition of "what a Flux path actually renders" in the harness.
 """
 from __future__ import annotations

+import bisect
 import os
 import re
 import sys
@@ -230,9 +339,18 @@ LEN_RE = re.compile(r"^#([A-Za-z_][A-Za-z0-9_]*)$")


 def classify(dollars: int, inner: str) -> tuple[str, str] | None:
-    """Return (severity-tag, remediation) for a hazardous expansion, else None."""
-    if dollars >= 2:
-        return None                                   # escaped: emitted as a literal
+    """Return (severity-tag, remediation) for a hazardous expansion, else None.
+
+    PARITY, not ">= 2" (the 2026-09-13 correction). envsubst consumes dollars in PAIRS and
+    emits one per pair, so a run of N dollars in front of a brace leaves the brace ESCAPED
+    only when N is EVEN. An ODD run emits floor(N/2) literal dollars and its last dollar is
+    still LIVE, so `$$${X}` expands exactly as `${X}` does — and `$$${ARR[0]}` fails the
+    whole Kustomization where `$${ARR[0]}` is harmless. The old `dollars >= 2 -> return None`
+    called every such run "escaped" and stopped looking. Assertion (7) flags the run itself;
+    this function additionally classifies the still-live expansion an odd run carries.
+    """
+    if dollars % 2 == 0:
+        return None                                   # fully escaped: emitted as a literal
    if NAME_RE.match(inner):
        if inner in KEYS:
            return None                               # defined knob — the happy path
@@ -267,6 +385,9 @@ def rendered_files(path_spec: str) -> tuple[list[str], bool]:
 findings: list[str] = []
 referenced: dict[str, set[str]] = {}
 inventory: list[str] = []
+# rel path -> the Kustomization name(s) that render it, for assertion (7)'s second pass.
+# A file can be rendered by more than one Kustomization; all of them substitute.
+subst_files: dict[str, set[str]] = {}

 for k in kustomizations:
    files, exists = rendered_files(k["path"])
@@ -280,13 +401,14 @@ for k in kustomizations:
            text = f.read_text()
        except (OSError, UnicodeDecodeError):
            continue
+        subst_files.setdefault(rel, set()).add(k["name"])
        for lineno, line in enumerate(text.splitlines(), 1):
            for m in TOKEN_RE.finditer(line):
                dollars, inner = len(m.group(1)), m.group(2)
                verdict = classify(dollars, inner)
                if verdict is None:
-                    if dollars >= 2:
-                        n_esc += 1
+                    if dollars % 2 == 0:              # PARITY, see classify(): an odd run is
+                        n_esc += 1                    # live, not escaped
                    else:
                        n_def += 1
                        referenced.setdefault(re.split(r"[:/#%^,]", inner)[0] or inner,
@@ -312,6 +434,156 @@ for k in kustomizations:
 check(not findings,
      f"{len(findings)} unescaped, undefined or unparseable expansion(s) in substituted paths")

+# ----------------------------------- (7) no dollar run is silently rewritten on the way out
+# THE 2026-09-13 CLASS. envsubst consumes dollars in PAIRS and emits one per pair,
+# unconditionally and everywhere (header: DOLLAR-RUN ARITHMETIC, measured against flux 2.4.0).
+# So every run of >= 2 dollars in a substituted manifest is REWRITTEN between git and the
+# container, and from the text alone the two intents are indistinguishable:
+#
+#   (a) a deliberate escape the author WANTS collapsed  — `$${VAR}` -> literal `${VAR}`;
+#   (b) content that must arrive VERBATIM               — `DO $$ ... $$;` -> `DO $ ... $;`
+#                                                          i.e. the incident. A BUG.
+#
+# THE RULE CHOSEN, AND WHY IT IS NEITHER NOISY NOR VACUOUS.
+# Exactly ONE shape passes unremarked: a run of EXACTLY TWO dollars immediately followed by
+# `{`. That is not a guess about intent, it is the escape contract this repo already
+# documents in clusters/base/apps-vms.yaml, that assertions (1)-(3) already validate the
+# inside of, and that 18 reviewed occurrences already rely on (unifi cloud-init, the gitea
+# and nextcloud OIDC bootstrap scripts, two longhorn comments). Failing those would be a
+# permanently-firing alert on documented, correct intent, and this repo has already been
+# bitten by one of those.
+#
+# EVERY OTHER run of >= 2 dollars FAILS unless it is named in `dollar-collapse.allow`:
+#   * DOLLAR-COLLAPSE   — a run not followed by `{`. Cannot survive verbatim: `$$` -> `$`.
+#                         This is the incident's exact shape and a blanket bug by default.
+#   * DOLLAR-HALF-ESCAPED — an ODD run >= 3 before `{`. Looks escaped, is not: the last
+#                         dollar is live. Occasionally legitimate (`$$${PRICE}` to render a
+#                         literal `$` before a value), so it is allowlistable, not banned.
+#   * DOLLAR-OVER-ESCAPED — an EVEN run >= 4 before `{`. Emits N/2 dollars then a literal
+#                         brace; nearly always a miscount, sometimes deliberate.
+#
+# WHY AN ALLOWLIST AND NOT A BLANKET BAN: a blanket ban was the first choice and was
+# rejected on evidence, not taste — main carries two real non-braced `$$` occurrences today
+# (prose inside embedded shell comments), so a blanket ban would have shipped RED. Nor is
+# the allowlist a hole: an entry is a hand-written edit to a file inside the conformance
+# test, which is loud in review; it must quote a >= 24-character VERBATIM context, so it can
+# only ever cover the occurrence it was written for and never a future one that drifts into
+# the same file; it must carry a >= 40-character reason; and every entry must still MATCH
+# something, so the allowlist cannot rot into a blanket exemption after the code it excused
+# is deleted. A wildcard, a bare `$$` context and a stale entry each FAIL.
+ALLOW_FILE = (ROOT / "conformance" / "tests" / "l0-static"
+              / "flux-postbuild-substitution" / "dollar-collapse.allow")
+MIN_CONTEXT = 24
+MIN_REASON = 40
+DOLLAR_RUN_RE = re.compile(r"\$+")
+
+allow_entries: list[dict] = []
+check(ALLOW_FILE.is_file(),
+      f"{ALLOW_FILE.relative_to(ROOT)} is missing — assertion (7) needs its allowlist to "
+      f"exist even when empty, because an absent file and an empty file are the same green "
+      f"and the next author would not know the mechanism is there")
+if ALLOW_FILE.is_file():
+    for lineno, raw in enumerate(ALLOW_FILE.read_text().splitlines(), 1):
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        parts = [x.strip() for x in raw.split("|")]
+        if len(parts) != 3:
+            check(False, f"dollar-collapse.allow:{lineno}: expected exactly 3 '|'-separated "
+                         f"fields (path | verbatim-context | reason), got {len(parts)}")
+            continue
+        allow_entries.append({"line": lineno, "path": parts[0], "ctx": parts[1],
+                              "reason": parts[2], "used": 0})
+
+for e in allow_entries:
+    tag = f"dollar-collapse.allow:{e['line']}"
+    check((ROOT / e["path"]).is_file(),
+          f"{tag}: names '{e['path']}', which is not a file in this repo — a stale entry is "
+          f"a standing exemption for a path someone could recreate")
+    check(len(e["ctx"]) >= MIN_CONTEXT,
+          f"{tag}: context {e['ctx']!r} is {len(e['ctx'])} chars; at least {MIN_CONTEXT} are "
+          f"required so an entry cannot be a near-wildcard that swallows future occurrences")
+    check(DOLLAR_RUN_RE.search(e["ctx"]) is not None
+          and max((len(m.group(0)) for m in DOLLAR_RUN_RE.finditer(e["ctx"])), default=0) >= 2,
+          f"{tag}: context {e['ctx']!r} contains no run of two or more dollars, so it excuses "
+          f"nothing and is either a typo or a decoy")
+    check(len(e["reason"]) >= MIN_REASON,
+          f"{tag}: reason is {len(e['reason'])} chars; at least {MIN_REASON} are required. "
+          f"State what envsubst will actually emit and why that is acceptable — an entry "
+          f"nobody had to explain is an accident wearing an approval")
+
+RUN_TAGS = {
+    "collapse": ("DOLLAR-COLLAPSE",
+                 "envsubst collapses each PAIR of dollars into one, everywhere and "
+                 "unconditionally, so this CANNOT reach the workload verbatim (a literal $$ "
+                 "needs $$$$ in source). This is the 2026-09-13 nextcloud-db shape: a "
+                 "dollar-quoted PL/pgSQL DO block arrived half-quoted and every Flux-"
+                 "reconciled run died. Rewrite without dollars, double them again if the "
+                 "collapse is what you want, or justify it in dollar-collapse.allow"),
+    "half": ("DOLLAR-HALF-ESCAPED",
+             "an ODD run of dollars before a brace is NOT escaped: floor(N/2) literal "
+             "dollars are emitted and the LAST dollar is still live, so this expansion "
+             "EVALUATES at reconcile time (and if its inner is unparseable it fails the "
+             "entire Kustomization). Use an EVEN run to escape, or justify it in "
+             "dollar-collapse.allow if a literal dollar before a substituted value is "
+             "really what you meant"),
+    "over": ("DOLLAR-OVER-ESCAPED",
+             "an EVEN run of four or more dollars emits N/2 literal dollars followed by a "
+             "LITERAL brace — the value is never substituted and extra dollars appear in "
+             "the rendered manifest. Almost always a miscount of the escape; justify it in "
+             "dollar-collapse.allow if it is not"),
+}
+
+run_findings: list[str] = []
+n_runs_ok = 0
+for rel in sorted(subst_files):
+    text = (ROOT / rel).read_text(errors="replace")
+    # Absolute offsets, not per-line: the gitea/nextcloud bootstrap scripts are single
+    # 4000-character folded scalars, so "the line" is not a reviewable unit of context here.
+    nl = [i for i, ch in enumerate(text) if ch == "\n"]
+    spans = []                                       # allowlisted [start, end) regions
+    for e in allow_entries:
+        if e["path"] != rel:
+            continue
+        start = text.find(e["ctx"])
+        while start >= 0:
+            spans.append((start, start + len(e["ctx"]), e))
+            start = text.find(e["ctx"], start + 1)
+    for m in DOLLAR_RUN_RE.finditer(text):
+        n = len(m.group(0))
+        if n < 2:
+            continue
+        braced = text[m.end():m.end() + 1] == "{"
+        if n == 2 and braced:
+            n_runs_ok += 1                           # the documented escape; (1)-(3) own it
+            continue
+        covering = [e for (a, b, e) in spans if a <= m.start() and m.end() <= b]
+        if covering:
+            for e in covering:
+                e["used"] += 1
+            continue
+        kind = "collapse" if not braced else ("half" if n % 2 else "over")
+        tag, fix = RUN_TAGS[kind]
+        lineno = bisect.bisect_right(nl, m.start()) + 1
+        ctx = text[max(0, m.start() - 60):m.end() + 60].replace("\n", "\\n")
+        run_findings.append(
+            f"  [{tag}] {rel}:{lineno}  a run of {n} dollar(s)"
+            f"{' before a brace' if braced else ''}\n"
+            f"        rendered by Flux Kustomization(s) {', '.join(sorted(subst_files[rel]))}"
+            f" — postBuild substitution REWRITES it\n"
+            f"        {fix}\n"
+            f"        | ...{ctx}...")
+
+check(not run_findings,
+      f"{len(run_findings)} dollar run(s) in substituted paths that envsubst rewrites and "
+      f"nothing justifies (the 2026-09-13 nextcloud-db class)")
+
+for e in allow_entries:
+    check(e["used"] > 0,
+          f"dollar-collapse.allow:{e['line']}: STALE — its context is not present in "
+          f"{e['path']} any more (or no longer contains a rewritten dollar run), so the entry "
+          f"now excuses nothing. Delete it. A stale allowlist is how an opt-in decays into a "
+          f"blanket exemption for whatever lands in that file next")
+
 # --------------------------------------------- (5) overlay knobs exist in the base
 # Parse contract: overlays patch cluster-vars with JSON6902 ops (`- op: replace` /
 # `path: /data/KEY`) inside an inline `patch: |-` block. The repo rule (cluster-vars.yaml
@@ -328,10 +600,27 @@ for overlay in sorted((ROOT / "clusters").glob("*/kustomization.yaml")):
 # ------------------------------------------------------- (6) the check is load-bearing
 L0 = (ROOT / "ci" / "l0.sh").read_text() if (ROOT / "ci" / "l0.sh").is_file() else ""
 GATE = (ROOT / "ci" / "gate.sh").read_text() if (ROOT / "ci" / "gate.sh").is_file() else ""
-check("flux-postbuild-substitution/check.sh" in L0,
-      "ci/l0.sh does not run flux-postbuild-substitution/check.sh — the requirement-scoped "
-      "conformance selection can filter this check out of a gate run, so l0.sh must invoke "
-      "it directly and unconditionally or the gate is not actually enforcing it")
+# THIS CHECK IS LOAD-BEARING — asserted against the DECLARATIVE mechanism.
+# It used to assert `"flux-postbuild-substitution/check.sh" in L0`: ci/l0.sh carried a hand-written
+# "UNCONDITIONAL" stage per whole-repo check, hardcoding this path. Those stages are gone
+# (they did not scale, and the next whole-repo invariant only got one if someone REMEMBERED
+# to write it). The same property is now asserted two ways: this test DECLARES
+# `conformance.home.k3s/scope: "whole-repo"`, and ci/l0.sh unions every declaring test into
+# the run via `--include-scope`. Neither half alone is enough, so both are checked here; the
+# mechanism ITSELF (the union really selects, and a scope-declared SKIP exits 3 rather than
+# passing) is proven end-to-end and falsifiably by
+# conformance/tests/l0-static/whole-repo-invariants-wired.
+SELF_YAML = ROOT / "conformance" / "tests" / "l0-static" / "flux-postbuild-substitution" / "chainsaw-test.yaml"
+SELF = SELF_YAML.read_text() if SELF_YAML.is_file() else ""
+check(re.search(r'^\s*conformance\.home\.k3s/scope:\s*["\']?whole-repo', SELF, re.M) is not None,
+      "flux-postbuild-substitution/chainsaw-test.yaml does not declare "
+      'conformance.home.k3s/scope: "whole-repo", so the merge gate selects this check only '
+      "when a change happens to touch one of the requirements it is labelled with. "
+      "The path map keys only clusters/* to R-ENV-02, so an edit to a SUBSTITUTED manifest under apps/ or platform/ attributes nothing and this check would be filtered out of exactly the change that empties a variable (the 2026-09-01 Cilium k8sServiceHost CNI outage)")
+check("--include-scope" in L0,
+      "ci/l0.sh no longer passes --include-scope to the conformance runner, so the L0 stage is "
+      "a purely requirement-scoped run again and the scope annotation is inert decoration — "
+      "this check would then run only by coincidence")
 check(re.search(r"^for s in .*\bl0\b.*; do", GATE, re.M) and re.search(r"fail\).*BLOCK=1", GATE),
      "ci/gate.sh does not set the merge block when the l0 stage fails")

@@ -345,6 +634,10 @@ print("Flux postBuild substitution inventory (per Kustomization):")
 for line in inventory:
    print(line)
 print(f"\ncluster-vars knobs defined: {len(KEYS)}   referenced: {len(referenced)}")
+print(f"dollar runs >=2 in substituted files: {n_runs_ok} documented $${{...}} escapes, "
+      f"{sum(e['used'] for e in allow_entries)} justified by dollar-collapse.allow "
+      f"({len(allow_entries)} entr{'y' if len(allow_entries) == 1 else 'ies'}), "
+      f"{len(run_findings)} unjustified")

 if ADVISORIES:
    print("\nADVISORIES (not failures):")
@@ -356,6 +649,12 @@ if findings:
    for f in findings:
        print(f, file=sys.stderr)

+if run_findings:
+    print("\nHAZARDS — dollar runs envsubst rewrites between git and the container:",
+          file=sys.stderr)
+    for f in run_findings:
+        print(f, file=sys.stderr)
+
 print()
 if not FAILURES:
    print(f"check OK: flux-postbuild-substitution — {CHECKS} assertions "