Repository navigation
Description
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 byJustfile(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.mdstates 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 documentssudo system-container start <name>as the operator-facing
lifecycle.AGENTS.mdline 65 routes operators to that skill.
Nothing installs it. On a real DDI,/usr/bin/system-containerdoes not exist.
The failure is silent in every gate we have:
tests/unit/system-container_test.batsexecutes 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 assertsfiles/bin/system-containerexists in the repo. .github/scripts/docs-checks.pyvalidates front-matter, budgets, and link
targets — it has no notion of whether a documented binary is staged.just validateonly runsbst show --deps allon 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 followdocs/skills/system-containers.mdon real
hardware getssystem-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 intofiles/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: thepath:in the element becomes stale and
nothing cross-checks the two sides.
Recommendation
- Make the payload rule explicit and enforced: every path under
files/is
either staged by an elementkind: localsource or is declared host-side
tooling. A drift gate intests/unit/can assert this from the element
graph, and can also assert the reverse direction — that every declared
path:still exists on disk. - Decide
system-containers side of that line. Either stage it (an import
element underelements/bluefin-server/added toos-stack.bst, which is a
behaviour change and belongs to a maintainer, not to this agent) or correct
docs/skills/system-containers.mdto 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
Activity
castrojo commentedon Sep 20, 2026
The detection half landed in #155 —
tests/unit/test_files_payload_reachability.pynow fails on any new orphan underfiles/, withfiles/bin/system-containerrecorded as the single shrink-only waiver citing this issue.Verified against the Kubernetes cutover branch (#210) as well: the new
files/cluster/**,files/kubernetes/**andfiles/os/libexec/**payload is all staged, so the waiver list stays at one entry.This issue stays open for the decision it actually asks for: does
system-containership (stage it from an element), or isdocs/skills/system-containers.mdwrong about/usr/bin/system-container? That is a maintainer call, not a test.hivecommons-hive commentedon Sep 20, 2026
A merged PR referenced this issue without closing it. Carrying the remainder back here so the issue timeline shows what is still open.
Remainder from the PR body:
rather than closing it.
This comment is edited in place by the task-list sweep on every cycle; it is not duplicated.
repires commentedon Sep 23, 2026
The actionable drift gate for this finding was merged in PR #155 (commit
afea1e7), addingtests/unit/test_files_payload_reachability.pywithfiles/bin/system-containerrecorded as the single shrink-only waiver citing this issue.As noted by @castrojo, all actionable automated verification has landed, and the issue remains open awaiting a maintainer product decision on whether to stage
system-containerinto the OS image via an import element or amenddocs/skills/system-containers.mdto remove the reference to/usr/bin/system-container. No further agent code changes are actionable without that decision.— hive: backend=agy
🐝 Hive Agent:
contributor| SHA:unknowndocs: accuracy pass after the FSDK rebase (projectbluefin#276)