konih · Oct 16, 2026 · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026
@@ -1,6 +1,6 @@
 {
   "name": "Kubebuilder DevContainer",
-  "image": "golang:1.26.9@sha256:d7722066f0b60ceccb6c0643cbed1f5f9e15506ac237146c95333504d7805d89",
+  "image": "golang:1.27.2@sha256:5bc7f572bbaa98885a3a1fd9c0aa76b59e3e14e8628bfc316bbfd0c701e4818c",
   "features": {
     "ghcr.io/devcontainers/features/docker-in-docker:2": {
       "moby": false,

@@ -21,7 +21,8 @@
 # no required context is at stake. Locked by hack/test/ci_docs_gate_test.sh.
 #
 # The docs-only path is NOT free, and that is a deliberate trade. Where this workflow previously
-# was not dispatched at all, a documentation-only PR now runs `changes`, `gitleaks` and `lint` --
+# was not dispatched at all, a documentation-only PR now runs `changes`, `gitleaks`, `lint` and
+# `tool-pins-selftest` (CFC-6, the tool-pins gate's self-test, split out of lint for wall time) --
 # `lint` because two existing gates (dist_ci_wiring_test.sh, repo_root_links_wiring_test.sh)
 # require it to be unconditional, and because it is where ci_docs_gate_test.sh runs, so leaving
 # it ungated is the only thing that exercises the docs-only direction at all. What such a PR no
@@ -539,9 +540,67 @@ jobs:
             bash "${script}"
             echo "::endgroup::"
           done
+      # CFC-1..CFC-6 (openspec change cross-file-consistency-gates): the cross-file consistency
+      # gates -- the Go toolchain agrees across go.mod, the Dockerfiles and the devcontainer
+      # (CFC-1), every pinned tool resolves and its analysis tools run under go.mod's Go (CFC-2),
+      # the chart's RBAC covers config/rbac/role.yaml in both install modes (CFC-3), registered
+      # metrics match the docs and rules (CFC-4), and the go-patch-lag sensor keeps its verdicts
+      # and its workflow shape (CFC-5). Plain and --self-test are separate steps (CFC-6): the
+      # first reds when the tree drifts, the second when a gate can no longer fail. They run here,
+      # unconditionally, because lint is a required context that also runs on docs-only PRs.
+      # Tools: jq (runner image), yq, helm and PyYAML installed above; Go from go.mod through
+      # go-cache (the tool-pins gate forces GOTOOLCHAIN=go<go.mod version> itself).
+      - name: Verify the Go toolchain agrees across go.mod, images and devcontainer (CFC-1)
+        run: bash hack/test/consistency_go_toolchain_test.sh
+      - name: Verify the Go toolchain gate can still fail (CFC-6)
+        run: bash hack/test/consistency_go_toolchain_test.sh --self-test
+      - name: Verify the chart RBAC covers role.yaml in both install modes (CFC-3)
+        run: bash hack/test/consistency_rbac_test.sh
+      - name: Verify the chart RBAC gate can still fail (CFC-6)
+        run: bash hack/test/consistency_rbac_test.sh --self-test
+      - name: Verify registered metrics match the docs and alert rules (CFC-4)
+        run: bash hack/test/consistency_metrics_test.sh
+      - name: Verify the metrics gate can still fail (CFC-6)
+        run: bash hack/test/consistency_metrics_test.sh --self-test
+      - name: Verify the go-patch-lag sensor verdicts and workflow shape (CFC-5)
+        run: bash hack/test/go_patch_lag_test.sh
+      - name: Verify the go-patch-lag test can still fail (CFC-6)
+        run: bash hack/test/go_patch_lag_test.sh --self-test
+      # Evidence under openspec/changes/**/evidence/ (archive included) is Markdown only: a probe
+      # script committed there is analysed by SonarCloud as uncovered new code although CI never
+      # runs it (decision 2026-10-16: inline probes in the evidence .md instead of widening
+      # sonar.exclusions). Plain and --self-test as separate steps, like the CFC gates above.
+      - name: Verify openspec evidence is Markdown only
+        run: bash hack/test/openspec_evidence_markdown_only_test.sh
+      - name: Verify the openspec evidence guard can still fail
+        run: bash hack/test/openspec_evidence_markdown_only_test.sh --self-test
+      # Network: the module proxy, golangci-lint's custom build and the vuln DB (about 30 s warm).
+      - name: Verify every pinned tool resolves and runs under go.mod's Go (CFC-2)
+        run: bash hack/test/consistency_tool_pins_test.sh
       - name: Lint
         run: task lint
 
+  # CFC-6 for CFC-2 (openspec change cross-file-consistency-gates): the tool-pins gate's
+  # --self-test builds each pinned analysis tool at its own and at a too-old version (about
+  # 7 minutes warm), so it runs in its own job, in parallel with lint, instead of doubling
+  # lint's wall time (operator decision 2026-10-16). Like lint it is NOT gated on the changes
+  # verdict: it runs on every PR, docs-only included, and is a required context
+  # (hack/release/verify-eligibility.sh). hack/test/ci_workflow_security_test.sh (CFC-6 rule)
+  # requires the self-test in this job and hack/test/ci_docs_gate_test.sh keeps the job
+  # unconditional. The timeout bounds a stalled module or vuln-DB download; local runs took
+  # 7 to 17 minutes.
+  tool-pins-selftest:
+    name: tool-pins-selftest
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/go-cache
+      - name: Verify the tool-pins gate can still fail (CFC-6)
+        run: bash hack/test/consistency_tool_pins_test.sh --self-test
+
   # CI-DOCSGATE-01: the REAL suite. It is deliberately NOT named `test` -- the required context
   # of that name is produced by the `test` job at the end of this file, which reports on every
   # PR. A job that legitimately skips must never carry a required context name; that is exactly

@@ -0,0 +1,36 @@
+# CFC-5 (openspec change cross-file-consistency-gates): red when go.mod's Go is behind the latest
+# patch of its minor, or when that patch cannot be determined (the lookup fails closed). A Go patch
+# carries stdlib security fixes; this makes the lag visible before govulncheck does.
+# Pinned by hack/test/go_patch_lag_test.sh (triggers, permissions, no secrets, one plain step,
+# curl's retry budget inside the step's timeout-minutes).
+name: Go patch lag
+
+on:
+  schedule:
+    - cron: "23 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: go-patch-lag-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  go-patch-lag:
+    name: go-patch-lag
+    runs-on: ubuntu-latest
+    # why: above the sensor step's own timeout, so checkout and runner setup cannot end the job
+    # before the step does.
+    timeout-minutes: 6
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Compare go.mod's Go with the latest patch of its minor
+        # why: curl's retry budget in the script (--retry-max-time + --max-time) must end inside
+        # this step's own timeout so a stalled go.dev fails with the script's message.
+        timeout-minutes: 5
+        run: bash hack/ci/go-patch-lag.sh
@@ -181,7 +181,7 @@ ENVTEST_K8S_VERSION ?= $(shell v='$(call gomodver,k8s.io/api)'; \
   [ -n "$$v" ] || { echo "Set ENVTEST_K8S_VERSION manually (k8s.io/api replace has no tag)" >&2; exit 1; }; \
   printf '%s\n' "$$v" | sed -E 's/^v?[0-9]+\.([0-9]+).*/1.\1/')
 
-GOLANGCI_LINT_VERSION ?= v2.13.1
+GOLANGCI_LINT_VERSION ?= v2.14.0
 .PHONY: kustomize
 kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
 $(KUSTOMIZE): $(LOCALBIN)

@@ -26,7 +26,7 @@ vars:
   GO_ARCH_LINT_GRAPH: docs/architecture-graph.svg
   MARKDOWNLINT_CONFIG: hack/tooling/markdownlint-cli2.yaml
   # renovate: datasource=github-releases depName=fe3dback/go-arch-lint
-  GO_ARCH_LINT_VERSION: v1.15.0
+  GO_ARCH_LINT_VERSION: v1.19.0
   # renovate: datasource=github-releases depName=helm/helm
   HELM_VERSION: v3.22.0
   # renovate: datasource=github-releases depName=norwoodj/helm-docs
@@ -201,7 +201,7 @@ tasks:
     desc: Scan for known Go vulnerabilities (govulncheck)
     deps: [install]
     cmds:
-      - go run golang.org/x/vuln/cmd/govulncheck@v1.1.4 ./...
+      - go run golang.org/x/vuln/cmd/govulncheck@v1.9.0 ./...
 
   test:
     desc: Run unit tests with envtest (alias for test:run)

@@ -12,7 +12,7 @@ Kubernetes cluster (typically [kind](https://kind.sigs.k8s.io/)).
 
 | Tool | Version / notes |
 | --- | --- |
-| [Go](https://go.dev/dl/) | **1.26.9+** (see `go.mod`) |
+| [Go](https://go.dev/dl/) | **1.27.2+** (see `go.mod`) |
 | [Docker](https://docs.docker.com/get-docker/) | For container image builds and kind |
 | [kubectl](https://kubernetes.io/docs/tasks/tools/) | 1.28+ recommended |
 | [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) | Local cluster for smoke / e2e |

@@ -100,6 +100,9 @@ All custom metrics use the `kollect_` prefix. Controller-runtime also exposes st
 | `kollect_reconcile_errors_total` | counter | `kind`, `error_class` | Errors by CR kind and class (`transient`, `terminal`, `forbidden`) |
 | `kollect_reconcile_duration_seconds` | histogram | `controller` | Reconcile latency |
 | `kollect_workqueue_depth` | gauge | `controller` | In-flight reconciles (approximate depth) |
+| `kollect_watch_map_list_errors_total` | counter | `controller`, `watch` | Secondary watch map handlers that failed to list related objects (RBAC or API list failures) |
+| `kollect_static_ref_resolution_total` | counter | `kind`, `ref_type`, `result` | Cluster-kind namespaced static-ref resolutions (`ok` / `not_found` / `forbidden`, [ADR-0208](../adr/0208-cluster-static-refs-via-namespace.md)) |
+| `kollect_access_cache_total` | counter | `result` | SelfSubjectAccessReview access-cache outcomes: `hit` serves a cached decision, `miss` issues a fresh review |
 
 ### Collection
 
@@ -118,6 +121,8 @@ All custom metrics use the `kollect_` prefix. Controller-runtime also exposes st
 | `kollect_export_bytes_total` | counter | `sink_type` | Payload bytes exported |
 | `kollect_sink_errors_total` | counter | `reason` | Export failures (`transient`, `terminal`, `forbidden`, `payload_too_large`, `spill_required`, …) |
 | `kollect_export_spill_warn_total` | counter | — | Payloads at/above 1 MiB spill warn threshold |
+| `kollect_export_shard_warn_total` | counter | — | Inventory namespace aggregates at/above the export sharding warn row threshold (~1800 rows) |
+| `kollect_namespace_fingerprint_cache_total` | counter | `controller`, `result` | Namespace content fingerprint cache outcomes: `hit` skips the snapshot + fingerprint recompute, `miss` pays for it |
 | `kollect_sink_connection_test_total` | counter | `type`, `result` | Git/TLS connection tests |
 | `kollect_cleanup_terminal_total` | counter | `kind` | Terminal sink-cleanup attempts on deleting objects (`inventory`, `cluster-inventory`). The cleanup finalizer is retained and the attempt re-checks every 5 minutes, so one wedged object increments the counter once per re-check — alert on any increase, not on the count; see [Troubleshooting](troubleshooting.md) |
 
@@ -157,7 +162,8 @@ sum(increase(kollect_sink_errors_total[15m])) by (reason)
 kollect_collect_items_total
 ```
 
-Source of truth for registration: `internal/metrics/metrics.go` and `internal/metrics/metrics_catalog.go`.
+Source of truth for registration: `internal/metrics/metrics.go` and `internal/metrics/aggregation*.go`.
+`internal/metrics/metrics_catalog.go` documents the same names for agents; it registers nothing.
 
 ## See also
 

@@ -1,6 +1,6 @@
 module github.com/platformrelay/kollect
 
-go 1.26.9
+go 1.27.2
 
 require (
 	cloud.google.com/go/bigquery v1.85.0

@@ -65,6 +65,7 @@ run_gate workflow-security-audit ./bin/zizmor --offline --no-progress --min-seve
 # TCE-3 mapping: required contexts whose local equivalent is a combination of the gates above.
 # hack/test/task_check_test.sh reads these lines; guard-sweep is the entry for the guard run.
 #   coverage: preflight=lint:markdown,go-mod,verify,guard-sweep
+#   coverage: tool-pins-selftest=guard-sweep
 
 
 # The guard sweep: every hack/test guard, bare, plus --self-test for the scripts that parse

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# CFC-5 (openspec change cross-file-consistency-gates): is go.mod's Go behind the latest patch of
+# its minor?
+#
+# Reads the `go` directive of go.mod and the go.dev release listing, and compares the directive
+# with the newest STABLE release of the same minor. A newer minor existing is reported as a note,
+# never as a failure. The lookup fails closed: an unreachable or unparsable listing, a minor the
+# listing does not carry, or a go.mod newer than the listing is a red run, never a green one.
+#
+# `&include=all` is required: the default listing carries only the two newest minors, so a go.mod
+# two minors behind would drop out of it and "behind" would read as "unknown".
+#
+# Exit codes: 0 current, 1 behind, 2 cannot determine (lookup failed or go.mod unreadable).
+#
+# Usage:
+#   hack/ci/go-patch-lag.sh [--gomod <go.mod>] [--listing <file> | --url <url>] [--retries <n>]
+#   --gomod    go.mod to read (default: the repository's)
+#   --listing  read the listing from a file instead of fetching it (tests)
+#   --url      listing URL (default: https://go.dev/dl/?mode=json&include=all)
+#   --retries  fetch retries (default 3; tests pass 0)
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+GOMOD="${ROOT}/go.mod"
+URL="https://go.dev/dl/?mode=json&include=all"
+LISTING=""
+RETRIES=3
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --gomod)
+      GOMOD="${2:?--gomod needs a path}"
+      shift 2
+      ;;
+    --listing)
+      LISTING="${2:?--listing needs a path}"
+      shift 2
+      ;;
+    --url)
+      URL="${2:?--url needs a URL}"
+      shift 2
+      ;;
+    --retries)
+      RETRIES="${2:?--retries needs a number}"
+      [[ "${RETRIES}" =~ ^[0-9]+$ ]] || { echo "go-patch-lag: --retries needs a number" >&2; exit 2; }
+      shift 2
+      ;;
+    *)
+      echo "go-patch-lag: unknown argument '$1'" >&2
+      exit 2
+      ;;
+  esac
+done
+
+minor_tag="?"
+undetermined() { echo "go-patch-lag: FAIL: cannot determine the latest go${minor_tag} patch: $*" >&2; exit 2; }
+
+command -v jq >/dev/null 2>&1 || undetermined "jq not found"
+
+# --- go.mod's directive -------------------------------------------------------------------------
+directive=""
+if [[ -f "${GOMOD}" ]]; then
+  directive="$(sed -nE 's/^go[[:space:]]+([^[:space:]]+)[[:space:]]*$/\1/p' "${GOMOD}")"
+fi
+# Canonical numbers of at most four digits: bash arithmetic reads 08 as bad octal (an arithmetic
+# error inside `if` is just "false") and wraps past 2^63 -- either way a false green.
+num='(0|[1-9][0-9]{0,3})'
+if [[ ! "${directive}" =~ ^${num}\.${num}\.${num}$ ]]; then
+  echo "go-patch-lag: FAIL: cannot read a go <major>.<minor>.<patch> directive from ${GOMOD} (found '${directive}')" >&2
+  exit 2
+fi
+minor_tag="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}"
+patch="${BASH_REMATCH[3]}"
+
+# --- the listing --------------------------------------------------------------------------------
+if [[ -z "${LISTING}" ]]; then
+  LISTING="$(mktemp)"
+  trap 'rm -f "${LISTING:?}"' EXIT
+  # Bounded well inside the workflow step's 5-minute timeout, so a stalled go.dev ends with this
+  # script's own message, not a killed step: <= 200 s of retries plus one 45 s attempt.
+  # hack/test/go_patch_lag_test.sh fails when --retry-max-time + --max-time outgrow that timeout.
+  curl -fsSL --proto '=https' --tlsv1.2 --connect-timeout 10 --max-time 45 \
+    --retry "${RETRIES}" --retry-all-errors --retry-max-time 200 -o "${LISTING}" "${URL}" ||
+    undetermined "fetching ${URL} failed"
+fi
+
+# Stable patch numbers of go.mod's minor, one per line; jq errors on anything but a JSON array.
+# shellcheck disable=SC2016 # $p is a jq variable
+jq_program='if type != "array" then error("not an array") else . end
+  | .[] | select(type == "object") | select(.stable == true)
+  | .version | select(type == "string") | select(startswith($p)) | ltrimstr($p)
+  | select(test("^(0|[1-9][0-9]{0,3})$"))'
+patches="$(jq -r --arg p "go${minor_tag}." "${jq_program}" "${LISTING}" 2>/dev/null)" ||
+  undetermined "the listing is not a JSON array of releases"
+latest="$(sort -n <<<"${patches}" | tail -n 1)"
+[[ -n "${latest}" ]] || undetermined "the listing has no stable go${minor_tag}.N release"
+
+# The newest stable release overall, for the newer-minor note only.
+newest="$(jq -r '[.[] | select(type == "object") | select(.stable == true) | .version
+  | select(type == "string") | capture("^go(?<a>[0-9]+)\\.(?<b>[0-9]+)\\.(?<c>[0-9]+)$")
+  | [(.a | tonumber), (.b | tonumber), (.c | tonumber)]] | max // empty
+  | "go\(.[0]).\(.[1]).\(.[2])"' "${LISTING}" 2>/dev/null || true)"
+
+if ((10#${patch} > 10#${latest})); then
+  undetermined "go.mod's go ${directive} is newer than go${minor_tag}.${latest}, the newest listed -- the listing is stale or go.mod names an unreleased Go"
+fi
+
+behind() {
+  echo "go-patch-lag: FAIL: go.mod's go ${directive} is behind go${minor_tag}.${latest}, the latest go${minor_tag} patch -- bump go.mod (and the golang images, CFC-1)" >&2
+  exit 1
+}
+if ((10#${patch} < 10#${latest})); then
+  behind
+fi
+echo "go-patch-lag: ok: go.mod's go ${directive} is the latest go${minor_tag} patch"
+if [[ -n "${newest}" && "${newest}" != "go${directive}" ]]; then
+  echo "go-patch-lag: note: a newer minor exists (${newest}); not a failure on its own"
+fi
@@ -10,7 +10,7 @@ trap 'rm -rf "${TMP}"' EXIT
 SHA="1111111111111111111111111111111111111111"
 MAIN="2222222222222222222222222222222222222222"
 
-REQUIRED_NAMES='gitleaks verify audit-rbac vulncheck lint test build test-integration helm docker-build preflight kind-smoke pipeline-cli-smoke workflow-security'
+REQUIRED_NAMES='gitleaks verify audit-rbac vulncheck lint test build test-integration helm docker-build preflight kind-smoke pipeline-cli-smoke workflow-security tool-pins-selftest'
 
 cat >"${TMP}/gh" <<'MOCK'
 #!/usr/bin/env bash

@@ -18,7 +18,7 @@ fi
 
 required_checks=(
 	gitleaks verify audit-rbac vulncheck lint test build test-integration helm
-	docker-build preflight kind-smoke pipeline-cli-smoke workflow-security
+	docker-build preflight kind-smoke pipeline-cli-smoke workflow-security tool-pins-selftest
 )
 
 main_sha="$(gh api "repos/${REPO}/commits/${DEFAULT_BRANCH}" --jq .sha)"