pal-e-docs

Review: IaC: manage workstation config with Salt and Woodpecker CI

review-1620-2026-06-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- present (standalone, discovered during archbox setup)
  • [x] Repo -- ldraney/hyprland-config
  • [x] User Story -- present and well-formed
  • [x] Context -- present with background and key decisions
  • [x] File Targets -- present with 10 create/modify targets and 2 do-not-touch targets
  • [x] Feature Flag -- present (none)
  • [x] Acceptance Criteria -- 5 criteria present
  • [x] Test Expectations -- present with dry-run, pipeline, and lint checks
  • [x] Constraints -- present (Salt patterns, NVIDIA pinning, idempotency, pacman/yay)
  • [x] Checklist -- present
  • [x] Related -- present

Traceability

  • [ ] story:gaming-stability label -- MISSING from project page. The project-hyprland-observability user-stories section lists: host-health, gpu-thermals, wm-state, dora-verified. "gaming-stability" is not among them. [SCOPE] Create user story entry "gaming-stability" on project-hyprland-observability user-stories section.
  • [ ] arch:iac label -- arch note MISSING. search_notes("arch-iac") returned no results. [SCOPE] Create architecture note arch-iac for component iac.
  • [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/hyprland-config/issues/9, state: open

File Targets

  • [ ] salt/ directory -- does NOT exist yet (to be created). Verified: correct, this is new work.
  • [ ] salt/top.sls -- does NOT exist yet (to be created). OK for feature ticket.
  • [ ] salt/packages/init.sls -- does NOT exist yet (to be created). OK.
  • [ ] salt/nvidia/init.sls -- does NOT exist yet (to be created). OK.
  • [ ] salt/steam/init.sls -- does NOT exist yet (to be created). OK.
  • [ ] salt/pipewire/init.sls -- does NOT exist yet (to be created). OK.
  • [ ] salt/dotfiles/init.sls -- does NOT exist yet (to be created). OK.
  • [ ] salt/pillar/ -- does NOT exist yet (to be created). OK.
  • [ ] .woodpecker.yml -- does NOT exist yet (to be created). OK.
  • [x] Makefile -- EXISTS at repo root. Currently has install, setup, console-rotate targets. Will be extended with Salt targets. Verified.
  • [x] hyprland.conf -- listed as do-not-touch. NOTE: file does not exist; the repo uses hyprland.lua instead. The ticket references hyprland.conf but the actual config is hyprland.lua. [BODY] Fix do-not-touch reference: hyprland.conf should be hyprland.lua.
  • [x] docs/architecture.md -- listed as do-not-touch (update separately). File exists. OK.

Repo Placement

Issue is filed on ldraney/hyprland-config. The fix lives in the same repo. Salt states and Woodpecker CI config will be added to this repo alongside existing dotfiles. The ticket mentions pal-e-platform as prior art for Salt patterns but does NOT propose changes there. Repo placement is correct -- single repo scope.

Dependencies

  • Item #1619 (Fix Steam/Palworld crash: IPC pipe failure + docs overhaul, 3pts, backlog) -- shares story:gaming-stability label. Not a hard dependency but related work. Both are in backlog, no blocking relationship.
  • External dependency: Salt must be installed on the workstation (not tracked on board).
  • External dependency: Woodpecker CI must be accessible on the home network (ticket states it is already deployed).
  • No documented dependencies in the issue body. External dependencies should be noted.

Acceptance Criteria

5 acceptance criteria present. Assessment:
  • AC1 (salt-call state.apply) -- verifiable via dry-run command provided in Test Expectations. However, full verification requires Salt to be installed and a minion configured, which is outside agent scope.
  • AC2 (Woodpecker CI runs on push) -- partially verifiable. Agent can create .woodpecker.yml but cannot verify Woodpecker actually triggers. Needs manual verification.
  • AC3 (add package to state, installs on next apply) -- verifiable in principle but requires running Salt. Testable via dry-run.
  • AC4 (NVIDIA drift detection) -- specific and verifiable. Good criterion.
  • AC5 (fresh Arch install provision) -- not verifiable by agent. Requires a fresh machine. This is an aspirational criterion, acceptable for a feature ticket.
Criteria are reasonable for infrastructure work. Most can be partially verified via dry-run.

Blast Radius

Searched for Salt and Woodpecker references in the repo -- none found. This is greenfield work with no existing patterns to conflict with. The Makefile will be extended (not replaced), so existing make targets (install, setup, console-rotate) must be preserved.
The ticket references hyprland.conf as do-not-touch, but the actual config file is hyprland.lua. The salt/dotfiles/init.sls state will need to reference hyprland.lua, not hyprland.conf.

Decomposition Assessment

10 file targets across 1 repo. 5 acceptance criteria. Estimated agent work: this is substantial -- creating an entire Salt state tree (7+ SLS files), a Woodpecker CI pipeline, and extending the Makefile. Estimated at >5 minutes of agent work.
NEEDS DECOMPOSITION -- 10 new files across multiple Salt state modules, plus CI pipeline, plus Makefile extension. Recommend splitting into:
  • Sub-ticket 1: Salt foundation (top.sls, pillar, packages/init.sls, Makefile salt targets) -- core state tree
  • Sub-ticket 2: Salt application states (nvidia, steam, pipewire, dotfiles) -- individual state modules
  • Sub-ticket 3: Woodpecker CI pipeline (.woodpecker.yml, lint/syntax validation)
Route to skill-decompose-ticket.

Recommendation

  • [BODY] Fix do-not-touch reference: hyprland.conf should be hyprland.lua (file does not exist as hyprland.conf)
  • [SCOPE] Create user story entry "gaming-stability" on project-hyprland-observability user-stories section
  • [SCOPE] Create architecture note arch-iac for component iac
  • [DECOMPOSE] 10 file targets, 5 AC, estimated >5 min agent work. Route to skill-decompose-ticket with 3-sub-ticket split: Salt foundation, Salt app states, Woodpecker CI.