Phase 1 audit harness in Python/uv reusing pinned clients; Node deferred to Phase 3

Date: 2026-06-07 Status: Accepted Decision: hl-bc5 Deciders: Sean Brandt

Context

Phase 1 of the docs migration builds a validation harness that shells out to lychee and talks to the cluster via Kubernetes and Vault clients. The Phase 3 target stack is Node (Astro/Starlight), so a toolchain choice was needed: introduce Node early for consistency, or stay in Python/uv — the repo’s existing convention, with kubernetes and hvac already pinned in pyproject.toml.

Decision

The Phase 1 audit harness is Python 3.13 + uv under tools/docs-audit/, reusing the already-pinned kubernetes, hvac, and PyYAML clients, with pytest added as a dev dependency. Node/pnpm is deferred to Phase 3 when website/ is scaffolded.

Rationale

• kubernetes and hvac are already pinned in pyproject.toml — zero new runtime dependencies for Phase 1.
• uv is the repo-mandated Python tool; introducing Node before it is needed violates YAGNI for a read-only audit phase with no Astro dependency.
• The cluster integration seams (live_namespaces, live_vault_paths_exist) need exactly these client APIs; no Node equivalents are pinned or vetted.

Alternatives Considered

• Node.js for the Phase 1 harness — single runtime across phases once Node arrives in Phase 3, but requires sourcing/pinning k8s and Vault client equivalents, breaks repo convention, and front-loads a runtime that Phase 1 does not need. Rejected.

Consequences

• Positive: the Phase 1 PR has no new runtime dependencies (uv sync --extra dev is the only setup); pure-logic modules are pytest-testable under the existing toolchain.
• Negative: Python and Node will coexist after Phase 3; contributors need both. Small helpers (e.g. first_h1) may be duplicated in the Phase 3 Node pipeline.
• Neutral: lychee is an external Rust binary regardless of harness language.