[architect] files/bin/system-container is unreachable payload: documented as /usr/bin/system-container but staged by no element

[kubestellar-hive]

Architecture Finding

Type: tech-debt / interface-violation (documented contract not backed by the build graph)
Affected area: files/bin/, elements/bluefin-server/os-stack.bst, docs/skills/system-containers.md, tests/unit/system-container_test.bats

Everything else under files/ is image payload that some element stages with a
kind: local source. The complete staged set today is:

element	path:
elements/bluefin-server/os-creds-prov.bst	files/os/sysusers.d
elements/bluefin-server/os-issue.bst	files/os/issue.d
elements/bluefin-server/os-justfile.bst	files/os/justfile
elements/bluefin-server/os-k0s-first-boot.bst	files/os/systemd/system
elements/bluefin-server/os-k0s-sysupdate.bst	files/os/sysupdate.k0s.d
elements/bluefin-server/os-kured-hook.bst	files/os/systemd/systemd-sysupdate.service.d
elements/bluefin-server/os-networkd.bst	files/os/systemd/network
elements/bluefin-server/os-sshd-config.bst	files/os/ssh
elements/bluefin-server/os-sshd-preset.bst	files/os/systemd/system-preset
elements/bluefin-server/os-sysupdate-keys.bst	files/os/sysupdate-keys
elements/bluefin-server/os-sysupdate.bst	files/os/sysupdate.d
elements/installer/installer-repart.bst	files/installer/repart.d
elements/oci/k0s-sysext.bst	files/k0s/sysext, files/k0s/manifests, files/k0s/kiosk, files/k0s/kubeflex, files/os/issue.d/40-kubestellar.issue

files/bin/ appears nowhere in that table. No element has a kind: local
source pointing at it, so nothing under files/bin/ reaches
oci/bluefin-server-ddi.bst, oci/bluefin-server-installer.bst, or
oci/k0s-sysext.bst.

Two files live there, and they are not the same kind of thing:

• files/bin/bluefin-kubestellar — host-side developer CLI, executed from the
  repository checkout by Justfile (install-vm, line 544) and
  scripts/lima-e2e-kubestellar-test.sh. Correctly not image payload.
• files/bin/system-container — claims to be image payload.
  docs/skills/system-containers.md states the helper is
  "/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),
  and documents sudo system-container start <name> as the operator-facing
  lifecycle. AGENTS.md line 65 routes operators to that skill.
  Nothing installs it. On a real DDI, /usr/bin/system-container does not exist.

The failure is silent in every gate we have:

• tests/unit/system-container_test.bats executes the script straight out of
  the repo, so it passes whether or not the script ships.
• The skills own acceptance checklist (docs/skills/system-containers.md
  line 100) only asserts files/bin/system-container exists in the repo.
• .github/scripts/docs-checks.py validates front-matter, budgets, and link
  targets — it has no notion of whether a documented binary is staged.
• just validate only runs bst show --deps all on the three OCI targets;
  an unreferenced source directory is invisible to it.

Impact

• A documented, tested, operator-facing command is absent from the shipped OS.
  The first person to follow docs/skills/system-containers.md on real
  hardware gets system-container: command not found, after the docs gate,
  the unit suite, and the build all reported green.
• The files/ tree has no stated rule separating image payload from host-side
  tooling, so the next helper dropped into files/bin/ inherits the same fate
  with no signal.
• Any future rename of a staged directory (e.g. files/os/ssh) silently
  removes payload from the image: the path: in the element becomes stale and
  nothing cross-checks the two sides.

Recommendation

1. Make the payload rule explicit and enforced: every path under files/ is
   either staged by an element kind: local source or is declared host-side
   tooling. A drift gate in tests/unit/ can assert this from the element
   graph, and can also assert the reverse direction — that every declared
   path: still exists on disk.
2. Decide system-containers side of that line. Either stage it (an import
   element under elements/bluefin-server/ added to os-stack.bst, which is a
   behaviour change and belongs to a maintainer, not to this agent) or correct
   docs/skills/system-containers.md to stop promising a binary the image does
   not carry.

A follow-up PR adds (1) only — the gate, with files/bin/system-container
recorded as the single known waiver so the gate passes today and fails the
moment a second orphan appears. (2) is deliberately left to maintainers.

---

Filed by architect agent (ACMM L5 — hold-gated mode)

🐝 Hive Agent: architect | Instance: hosted-projectbluefin-knuckle-gjvq | SHA: 4c1e7a7

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