From c9ace41340db442cf77403b4faec84ae1d46cf09 Mon Sep 17 00:00:00 2001
From: Vuong Hoang <vh@phasefinal.com>
Date: Mon, 5 Oct 2026 08:03:47 -0700
Subject: [PATCH] feat(check-backup-freshness): attach the documented reason to
 each policy exclusion

The policy section said WHICH guests are uncovered but not WHY, so every
reader had to reconstruct the ruling from memory or the bus. A missing
reason now prints as 'NO DOCUMENTED REASON', which turns an undocumented
new exclusion into a visible flag instead of a silent line.
---
 scripts/check-backup-freshness.sh | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/scripts/check-backup-freshness.sh b/scripts/check-backup-freshness.sh
index 39ee726..7b6dafd 100755
--- a/scripts/check-backup-freshness.sh
+++ b/scripts/check-backup-freshness.sh
@@ -59,6 +59,20 @@ declare -A NS_NODE=(
 declare -A NS_JOBS=()      # ns → one "enabled|all|vmids|excludes" line per job
 declare -A NS_KNOWN=()     # ns → 1 once coverage was successfully read
 
+# WHY each policy-excluded guest is out of the backup jobs (2026-10-05). The
+# exclusion is derived from jobs.cfg coverage; the REASON is standing policy
+# and lives here so the report can say why instead of asking the reader to
+# remember. Keep one line per guest with its paper trail; if an entry shows up
+# in the policy section with no reason, that is the flag: undocumented hole.
+declare -A EXCLUDE_WHY=(
+  [ana-pve/vm/101]="retired/shut down — Prime ruling 2026-10-04 (bus 01M44MEXG60); last snapshots kept"
+  [nh3-pve/vm/104]="retired/shut down (nh3-laser) — Prime ruling 2026-10-04 (bus 01M44MEXG60); last snapshots kept"
+  [ana-pve/ct/114]="subnet-router (ana-scale) — vzdump lock risk; ESH-scale lock once blackholed the site; rebuildable from config (docs/pfi/proxmox-inventory-2026-10-02.md)"
+  [nh3-pve/ct/107]="subnet-router (nh3-scale) — same scale-router class as ana/esh-scale; rebuildable from config"
+  [esh-pve/ct/108]="subnet-router (esh-scale) — its vzdump lock blackholed the ESH site; rebuildable from config"
+  [esh-pve/vm/102]="Windows Parsec/RDP sandbox, no needed state — Prime ruling 2026-09-19 (playbooks/esh-exclude-vm102-from-backup.yaml)"
+)
+
 # Every PVE node whose vzdump TASK RESULTS we read. Unlike jobs.cfg this is
 # per-NODE, not cluster-wide, so both ESH nodes appear. sfsrv is absent: tenant.
 PVE_NODES=(
@@ -201,7 +215,7 @@ if [ -z "$pbs" ]; then errors+=("PBS-ANA: unreachable or no snapshots"); else
     is_covered "$ns" "$vmid"
     case $? in
       1) excluded+=("pbs/$guest: no enabled vzdump job covers it$(
-           [ -n "$ep" ] && printf ' (last snapshot %s)' "$(date -d "@$ep" '+%Y-%m-%d' 2>/dev/null)")") ;;
+           [ -n "$ep" ] && printf ' (last snapshot %s)' "$(date -d "@$ep" '+%Y-%m-%d' 2>/dev/null)") — ${EXCLUDE_WHY[$guest]:-⚠ NO DOCUMENTED REASON — check this exclusion is intentional}") ;;
       *) report "pbs/$guest" "$ep" ;;
     esac
   done <<<"$pbs"