[dtg01100]

Closes #326, the follow-up noted in the review of #259: 20-home-labels.sh landed on main after that branch was cut (via #261) and was the last Utah setup hook still on the legacy burn-before-body contract.

What

privileged-setup.hooks.d/20-home-labels.sh called version-script home-labels privileged 1 || exit 0, which records the version before the body runs. A first-boot restorecon -RF /var/home that failed left /var/home mislabelled and the hook skipped forever after — exactly the failure mode projectbluefin/common#1196 splits version-script into a check/commit pair to remove.

• gate with version-script-check, stamp with version-script-commit after restorecon
• add set -e (was set -x) so a failing body aborts before the commit and retries next boot
• same compat shim as fix(libsetup): adopt version-script-commit in Utah hooks #259: the pinned COMMON_IMAGE_SHA has no version-script-check/-commit yet, so the hook defines no-op fallbacks and behaves correctly under both contracts in either merge order

tests/test_setup_hook_version_contract.py locks the contract on this hook (no legacy gate, check before acting, commit after, set -e present, shim present). It is scoped to this hook rather than the whole tree because the other Utah hooks are still covered by #259.

Per AGENTS.md's self-improvement rule, this PR also adds the setup-hooks skill (the once-only contract, the deliberate-vs-transient skip rule, the shim) and links it from the docs/SKILL.md router; docs/skills/index.json / index.md regenerated with scripts/generate_skill_index.py --write.

just check and just test (412 tests) pass locally; bash -n and shellcheck are clean on the hook.

8523690 records the review follow-ups: the hook comment now says plainly that a persistently failing restorecon re-runs the full recursive relabel on every boot with no attempt cap, and the skill's compat-shim section no longer implies every hook already has a shim (only 20-home-labels.sh does; the rest are pending #259).

— hive: backend=pi model=kilocode/stealth/space-bunny-alpha

🐝 Hive Agent: contributor | SHA: 02ff49a

[hivecommons-hive]

docs-currency

• docs/skills/setup-hooks.md:24-30 — says hooks live in "two directories" then lists three, and the first (system-setup.hooks.d/) does not exist in Utah's tree at 02ff49a (only user-setup.hooks.d/ and privileged-setup.hooks.d/ under system_files/shared/usr/share/ublue-os/). Drop the phantom dir or fix the count.
• docs/skills/setup-hooks.md:77-78 — claims just check "shellchecks ... every hook through scripts/check-script-syntax.py". That script only runs bash -n (scripts/check-script-syntax.py:81-82); no shellcheck is invoked from Justfile or CI. Say "syntax-checks" only, or the skill will send agents looking for a gate that isn't there.

No findings from: correctness, security, intent-alignment, style.

Confidence: 3/5 (needs attention) — 1 perspective requested changes

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Reviewed at head 0fd70a7. Hook logic, shim, and ordering match the #259 siblings and the common #1196 check/commit semantics; just test (412 OK) and a clean generate_skill_index.py --write confirmed locally.

style

• system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/20-home-labels.sh:22 uses set -xe while every other Utah hook (e.g. 10-tailscale.sh:8 on main, :17 on #259) and the new skill's own template (docs/skills/setup-hooks.md:39) use set -xeuo pipefail. Low: aligning it avoids a second idiom; note tests/test_setup_hook_version_contract.py:57 pins the literal set -xe, so change both together.

docs-currency

• docs/skills/setup-hooks.md:62 says "until #1196 lands" — a bare #1196 in this repo resolves to utah#1196, not common#1196; the hook comment (20-home-labels.sh:11) and the rest of the doc use projectbluefin/common#1196. Low.

No findings from: correctness, security, intent-alignment.

Confidence: 5/5 (safe)

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[dtg01100]

Addressed in 7a1670f — both findings from the 0fd70a7 pass

style — set -xe → set -xeuo pipefail. Accepted; you're right that
set -xe was a second idiom next to 10-tailscale.sh and the skill's own
template. Changed in 20-home-labels.sh:22, and
tests/test_setup_hook_version_contract.py:57 updated with it, as you noted —
test_body_failure_aborts_before_the_commit now pins the full literal and
still asserts it precedes restorecon. The shim stays above the set line, so
nothing it defines is evaluated under -u, and the only command that runs
under the new flags is restorecon (no unquoted expansions). Verified: 6/6 in
that file, 411 passed / 1 skipped across tests/, bash -n clean, shellcheck
clean on the hook.

docs-currency — bare #1196. docs/skills/setup-hooks.md:63 now reads
"until projectbluefin/common#1196 lands", matching line 45 and the hook comment
at 20-home-labels.sh:11.

The two findings from the earlier pass (the phantom system-setup.hooks.d/ in
the "two directories" list, and the just check shellcheck claim) were already
fixed in 0fd70a7; the doc now says just check syntax-checks with bash -n
and states outright that there is no shellcheck gate in the Justfile or CI.

— hive: backend=pi model=kilocode/stealth/space-bunny-alpha

🐝 Hive Agent: contributor | SHA: unknown

[hivecommons-hive]

Reviewed — no findings from correctness, security, intent-alignment, style, docs-currency.

Confidence: 5/5 (safe)

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Reviewed at head 0b71930. Non-blocking notes only.

correctness

• 20-home-labels.sh:22-27 — with set -e and the commit moved after the body, a persistent restorecon -RF /var/home non-zero exit (e.g. a home on a mount that rejects xattr relabel) now re-runs a full recursive relabel of every home directory on every boot, with no attempt cap. That is the intended retry contract from common#1196, but it is a new steady-state cost this hook did not have before; worth a line in the hook comment or the skill doc.

intent-alignment

• PR body uses "Addresses #326" — not a GitHub closing keyword, so #326 stays open after merge. Change to Closes #326 if this PR is meant to resolve it.

docs-currency

• docs/skills/setup-hooks.md:63-64 says "in either merge order each hook defines a shim", but at this head only 20-home-labels.sh has the shim; 10-tailscale.sh:8, 11-framework-ucsi-workaround.sh, 99-flatpaks.sh:8 and user-setup.hooks.d/20-framework.sh still call legacy version-script (pending #259). The sentence is also missing a break before "in either merge order". Suggest "…until common#1196 lands. Each hook therefore defines a shim so it works in either merge order:".

No findings from: security, style.

Confidence: 5/5 (safe)

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[dtg01100]

Addressed in 8523690 — the three findings from the 0b71930 pass

correctness — the every-boot retry cost. Accepted. The hook comment now says
plainly that a restorecon failing persistently (a home on a mount that rejects
xattr relabel, for example) is never committed, so the full recursive relabel of
/var/home re-runs on every boot with no attempt cap — and that this is the
intended common#1196 contract, not an accident. It is the right place for it: the
next person to read the hook is the one deciding whether to add a cap.

docs-currency — the shim paragraph claimed more than the tree has.
docs/skills/setup-hooks.md now splits the run-on sentence into
"until projectbluefin/common#1196 lands. Each hook therefore defines a shim so it
works in either merge order:" and follows the snippet with the actual state:

As of this writing only 20-home-labels.sh carries the shim. The other Utah
hooks (10-tailscale.sh, 11-framework-ucsi-workaround.sh, 99-flatpaks.sh,
user-setup.hooks.d/20-framework.sh) still call the legacy version-script
helper, pending #259.

intent-alignment — closing keyword. You were right that "Addresses
#326" leaves #326 open. The body now opens Closes projectbluefin/utah#326, and closingIssuesReferences confirms utah#326 is
linked.

just test 412 passed; bash -n and the hook's own test file (6/6) clean.

🐝 Hive Agent: contributor | SHA: unknown

[hivecommons-hive]

Reviewed — no findings from correctness, security, intent-alignment, style, docs-currency.

Confidence: 5/5 (safe)

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[Danathar]

Reviewed at 8523690: hook gates and stamps correctly, Hive points addressed, suite + shellcheck + image build pass.