[architect] test: files/ payload reachability gate — tests/unit/test_files_payload_reachability.py

[kubestellar-hive]

Refactor

Adds one file: tests/unit/test_files_payload_reachability.py. No element,
payload, workflow, or document is modified.

Cluster claimed

• New file: tests/unit/test_files_payload_reachability.py
• Read-only inputs: elements/**/*.bst (parsed for kind: local path:
  sources), the files/ tree listing.
• Not touched: elements/bluefin-server/os-stack.bst,
  elements/oci/k0s-sysext.bst, files/k0s/sysext/k0s-manifests.conf,
  tests/unit/test_k0s_manifests.py, tests/unit/test_kubestellar_kiosk.py,
  .github/scripts/docs-checks.py, files/installer/repart.d/**,
  include/flatcar.yml, elements/flatcar/**, renovate.json, files/bin/**,
  docs/**.

The structural problem

files/ is the image-payload tree. A file reaches an image only when some
element stages it with a kind: local source:

sources:
  - kind: local
    path: files/os/sysupdate.d

Nothing cross-checks the two sides. A directory under files/ that no element
names is invisible to just validate (which only runs bst show --deps all on
oci/bluefin-server-ddi.bst, oci/bluefin-server-installer.bst, and
oci/k0s-sysext.bst), invisible to the image build, and invisible to the unit
suite, because bats tests execute helper scripts straight out of the checkout
whether or not they ship. The reverse direction is equally unguarded: a
renamed payload directory leaves a stale path: on the element and quietly
removes the payload from the image.

files/bin/system-container is the live instance — docs/skills/system-containers.md
calls it "/usr/bin/system-container ... shipped in the OS image" (line 18)
and "The OS image ships a small helper at /usr/bin/system-container" (line 38),
tests/unit/system-container_test.bats covers it, and no element stages it.
Full analysis in #154.

What the gate asserts

• test_declared_source_paths_exist — every kind: local path: declared by
  any element still exists on disk (parametrized per declared path).
• test_every_payload_file_is_staged_or_declared — every file under files/
  is staged by an element, declared host tooling, or a recorded waiver.
• test_host_tooling_declarations_are_not_stale — HOST_TOOLING
  (files/bin/bluefin-kubestellar, files/lima) still exists and is still
  unstaged.
• test_known_unstaged_waivers_are_still_unstaged — KNOWN_UNSTAGED is
  shrink-only: staging a waived path fails the gate until the waiver is deleted,
  so the record cannot outlive the bug it describes.
• test_at_least_one_element_stages_payload — guards the gate itself, so a
  parser regression cannot make it vacuously pass.

KNOWN_UNSTAGED holds exactly one entry, files/bin/system-container, citing
#154. The gate therefore passes today and fails the moment a second orphan
appears.

Deliberately not fixed here

Staging system-container into the image is a behaviour change (it adds a
binary to the shipped OS) and correcting the skill is a documentation decision.
Both belong to a maintainer. This PR only makes the invariant checkable, which
is why it references #154 rather than closing it.

Verification

• python3 -m pytest tests/unit -q → 235 passed, 1 xfailed (was 211 passed, 1 xfailed; +24 from this file, all parametrized or new).
• python3 .github/scripts/docs-checks.py → Docs checks passed.
• Mutation-tested, each reverted afterwards:
  • added files/os/orphan/thing.conf → fails with
    assert not ['files/os/orphan/thing.conf'];
  • renamed files/os/ssh → fails with elements/bluefin-server/os-sshd-config.bst declares a kind: local source path that does not exist: files/os/ssh;
  • repointed an element at files/bin/system-container → fails with
    files/bin/system-container is now staged by an element. Remove it from KNOWN_UNSTAGED.

Picked up automatically by just test-unit and .github/workflows/unit-tests.yml;
no workflow change needed.

Refs #154 — the gate lands here; deciding whether system-container ships or
the docs are corrected is left open for maintainers.

---

Filed by architect agent (ACMM L5 — hold-gated mode). Hold-gated: human review required.

— hive: agent=architect backend=copilot model=claude-opus-5