[architect] composite-action inventory restated 3× with no drift gate: README.md, docs/skills/composite-actions.md, docs/skills/composite-actions/action-reference.md already disagree

[kubestellar-hive]

Architecture Finding

Type: tech-debt / drift
Affected area: README.md, docs/skills/composite-actions.md (Action catalog table), docs/skills/composite-actions/action-reference.md, vs. the on-disk action roster (bootc-build/*/action.yml, .github/actions/*/action.yml, actions/*/action.yml)

The repository ships 19 composite actions on disk, and restates that roster in three hand-maintained inventories. Nothing checks the restatements against the filesystem, and all three have already drifted apart:

Action (on disk)	README.md	composite-actions.md catalog	action-reference.md
bootc-build/apply-pkg-intervals	missing	listed	listed
bootc-build/create-release	missing	listed	listed
bootc-build/rechunk	listed	missing	missing
actions/check-token-health	missing	missing	out of scope
actions/retry	missing	missing	out of scope

docs/skills/composite-actions/action-reference.md advertises itself as the "Full action-by-action reference for all bootc-build composite actions" yet has no rechunk section, while composite-actions.md claims chunka is "the single rechunk implementation" without acknowledging that bootc-build/rechunk is still shipped, contract-frozen in docs/consumer-contract.yml, and covered by tests/bats/test_rechunk.bats.

docs/consumer-contract.yml is deliberately narrower (out-of-org consumer surface only) and is not part of this finding.

Impact

• Agents and consumers reading the skill docs cannot discover rechunk, apply-pkg-intervals, check-token-health, or retry depending on which inventory they open.
• Every new action added under bootc-build/ or actions/ silently lands undocumented; three separate reviewers would have to notice three separate omissions.
• The repo already enforces single-source invariants by test (tests/test_trust_policy_single_source.py, tests/test_release_gate_single_source.py, tests/test_no_orphaned_trust_material.py). The action roster is the one inventory with no such gate.

Recommendation

Add a pytest drift gate that treats the filesystem as the single source of truth and fails when any action directory is absent from an inventory that claims to be complete, then repair the three current omissions. Scope per inventory:

• README.md — every action directory in bootc-build/, .github/actions/, actions/
• docs/skills/composite-actions.md Action catalog — same roster
• docs/skills/composite-actions/action-reference.md — every bootc-build/ action (its declared scope)

---

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

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

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