---
name: dotfiles-tier-live-audit
description: "Audit the command-center dotfiles tier before running deploy.sh: prove per-file tracked/deployed state, refuse generated theme output, catch stale zz overrides, wrong-box dconf keys, and unresolvable systemd ExecStart specifiers."
---

# Deploy-tier audit (`~/.omp` command center)

Run **before** any real `scripts/deploy.sh` on a box with a live session, and whenever a
symlink, palette, wallpaper or unit behaves oddly. Facts and laws live in
`omp-docs/tools/dotfiles-deploy.md` + `omp-docs/inventory/home-config-census.md` — this page
is only the probe order. Do not restate the laws in new files; the vault owns them.

## 0. Classify per file, never per directory

```bash
cd ~/.omp
for f in $(git ls-files dotfiles/<pkg>); do t=$(readlink -f "$HOME/${f#dotfiles/<pkg>/}")
  printf '%-50s %s\n' "${f#dotfiles/<pkg>/}" "$([ -L "$HOME/${f#dotfiles/<pkg>/}" ] && echo LINK || echo real)"
done
```
A live directory can be real and still fully tracked (every file a symlink). `niri` 8/2,
`gtk-3.0` 3/0. `zz-$HOST` files count in the `zz` tier's row, not the base package's.

## 1. The plan, and how to read it

```bash
./scripts/deploy.sh --check    # writes nothing; read the last line, not the RELINK lines
```
`--check` prints `RELINK` for **every** path the `zz` tier carries even when the live link
already points at the override (base is walked first, intermediate owner change reported).
Only `actions=0` is a real summary; confirm a pending change with `readlink`.

## 2. Generated theme output must never be tracked or deployed

```bash
git ls-files dotfiles | grep -Ei 'noctalia\.(kdl|toml|json|conf|css)|themes/noctalia'
```
Hit = generated palette output (same-millisecond mtime cluster proves it). Untrack
(`git rm --cached` + `.gitignore` patterns); `deploy.sh` refuses the class (`SKIP … generated
theme output`). Tracking one means the next sync quarantines the user's live palette and
restores the committed colours.

## 3. Stale `zz` overrides

For each path present in both base and `zz-$HOST`: `diff` them, then compare each file's
`git log -1 --date=short`. A `zz` copy older than the base change is a time bomb — sync
relinks cross-package owners **silently** (`nothing to quarantine`). Delete the `zz` copy in
the same commit that base absorbed.

## 4. dconf: compare key by key, never with `diff`

`dconf load /` writes only keys present, so a text diff misleads both ways. Parse both sides
into `[section]/key → value` and report: value conflicts, keys the dump would newly write,
and any value containing `/home/` (foreign-box state). File-chooser `last-folder-path`,
`window-state`, `picture-uri*` are state, not preferences — delete them from the dump and
clear the live keys if they were already deployed here.

## 5. Units: state, then resolvability

```bash
for u in <units in dotfiles/systemd-user>; do printf '%s %s %s\n' "$u" \
  "$(systemctl --user is-enabled $u)" "$(systemctl --user is-active $u)"; done
```
`is-enabled` exits **1** for `linked` exactly as for `disabled` — read the printed word.
Never start a unit that is already installed: `swayidle-lock` sits `enabled`/`inactive` and
`--now` arms a screen lock mid-session. Specifiers are systemd's, not the shell's: probe
`command -v "${bin//%h/$HOME}"` before believing `ExecStart … absent on this host` — the
literal `%h/…` string made this repo's own heartbeat look foreign on every box.

## 6. Landing it

`bats tests/` (deploy contract runs `scripts/deploy.sh` in a scratch repo with `DEPLOY_REPO`,
`DEPLOY_HOST`, stub `HOME`, stub `systemctl` on `PATH`) + `scripts/kb-lint.sh omp-docs` +
`scripts/kb-coverage.py omp-docs`. Branch off `origin/main`, PR, never merge without Frank's
OK (`gitea-merge-form-encoded`: form-encoded `do=merge`, `merge_style=no-ff`).

Then deploy from the **deployment root** `~/.omp` only — never from a worktree (live symlinks
would point into a checkout the heartbeat reaps in 7 days). Acceptance: `actions=N
quarantined=0`, two consecutive `--check` runs both `actions=0`, no `ENABLE … started` for a
unit that was already installed.