Cluster cross-check is advisory only; never a CI gate
Date: 2026-06-07 Status: Accepted Decision: hl-yrh Deciders: Sean Brandt
Context
Section titled “Context”The docs validation harness adds a live-cluster cross-check that reconciles services.md, secrets.md, and network.md against the running cluster via read-only Kubernetes and Vault clients. GitHub Actions runners have no network path to the private cluster, and the k8s MCP is local/read-only. A decision was needed on whether this check could ever become a PR-blocking CI gate.
Decision
Section titled “Decision”The cluster cross-check ships as a local target (uv run python tools/docs-audit/audit.py --check cluster) and optionally an in-cluster CronJob posting findings to ntfy. It is never wired into CI as a build gate.
Rationale
Section titled “Rationale”- GitHub Actions runners cannot reach the private cluster; gating would require a cluster-accessible runner or VPN credentials in CI — significant new attack surface for marginal benefit.
- The check is bounded to the reference docs and is inherently advisory; the advisory framing resists scope creep into building a full reconciler.
- The CronJob→ntfy path provides async drift visibility without blocking PR workflows.
Alternatives Considered
Section titled “Alternatives Considered”- CI gate via VPN or cluster-side runner — automated enforcement of reference-doc accuracy, but requires maintaining cluster credentials/network access in CI and significantly expands scope. Rejected.
Consequences
Section titled “Consequences”- Positive: no cluster-credential exposure in CI; the cross-check scope stays bounded; Phase 1 ships with zero cluster-connectivity requirement in CI.
- Negative: reference-doc drift is not caught automatically on PRs; running the check requires local discipline (or the CronJob, which may slip to a follow-up).
- Neutral: the
cluster.pyintegration seams are implemented in Phase 1 for local use either way — this decision only constrains CI wiring.