feat(kb): monthly hygiene report for agent KB nodes

Phase 4 of the agent KB spec. kb-hygiene.sh inventories :agent: nodes, flags orphans (no id: link anywhere in the KB points at them), duplicate titles, and stray conflict files, then writes an org report into the rulesets inbox for the normal inbox flow to propose dispositions. Read-only by design — it never deletes. A monthly systemd user timer (Persistent=true) runs it; bats covers the counts, orphan detection, duplicates, conflict tally, and the missing-KB error path.

1 files changed, 87 insertions, 0 deletions

diff --git a/scripts/tests/kb-hygiene.bats b/scripts/tests/kb-hygiene.bats
new file mode 100644
index 0000000..a9f9e58
--- /dev/null
+++ b/scripts/tests/kb-hygiene.bats
@@ -0,0 +1,87 @@
+#!/usr/bin/env bats
+# Tests for scripts/kb-hygiene.sh — the monthly agent-KB hygiene report.
+
+setup() {
+  SCRIPT="$BATS_TEST_DIRNAME/../kb-hygiene.sh"
+  KB="$BATS_TEST_TMPDIR/kb"
+  OUT="$BATS_TEST_TMPDIR/inbox"
+  mkdir -p "$KB/agents" "$OUT"
+
+  # A hand-authored node that links to agent node AAA.
+  cat > "$KB/20240101000000-craig-note.org" << 'EOF'
+:PROPERTIES:
+:ID:       craig-1111
+:END:
+#+title: Craig's note
+
+See [[id:agent-aaa][the agent fact]].
+EOF
+
+  # Agent node AAA — linked from Craig's note (not an orphan).
+  cat > "$KB/agents/20250101000000-linked-fact.org" << 'EOF'
+:PROPERTIES:
+:ID:       agent-aaa
+:END:
+#+title: Linked fact
+#+filetags: :agent:reference:
+
+A fact someone links to.
+EOF
+
+  # Agent node BBB — nothing links to it (orphan).
+  cat > "$KB/agents/20250102000000-orphan-fact.org" << 'EOF'
+:PROPERTIES:
+:ID:       agent-bbb
+:END:
+#+title: Orphan fact
+#+filetags: :agent:reference:
+
+Nobody links here.
+EOF
+}
+
+@test "missing KB path: exits nonzero with a message" {
+  run "$SCRIPT" "$BATS_TEST_TMPDIR/nope" "$OUT"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"no KB"* ]]
+}
+
+@test "writes a dated report file into the report dir" {
+  run "$SCRIPT" "$KB" "$OUT"
+  [ "$status" -eq 0 ]
+  ls "$OUT" | grep -q "kb-hygiene-report.org"
+}
+
+@test "counts agent nodes correctly" {
+  run "$SCRIPT" "$KB" "$OUT"
+  report=$(ls "$OUT"/*kb-hygiene-report.org)
+  grep -q "Agent nodes: 2" "$report"
+}
+
+@test "flags the orphan and not the linked node" {
+  run "$SCRIPT" "$KB" "$OUT"
+  report=$(ls "$OUT"/*kb-hygiene-report.org)
+  grep -q "orphan-fact" "$report"
+  ! grep -A2 "Orphans" "$report" | grep -q "linked-fact"
+}
+
+@test "flags duplicate agent titles" {
+  cat > "$KB/agents/20250103000000-dupe.org" << 'EOF'
+:PROPERTIES:
+:ID:       agent-ccc
+:END:
+#+title: Orphan fact
+#+filetags: :agent:reference:
+EOF
+  run "$SCRIPT" "$KB" "$OUT"
+  report=$(ls "$OUT"/*kb-hygiene-report.org)
+  grep -qi "duplicate" "$report"
+  grep -c "Orphan fact" "$report" | grep -qv '^0$'
+}
+
+@test "reports sync-conflict file count" {
+  touch "$KB/junk.sync-conflict-20260101-000000-XXXX.org"
+  run "$SCRIPT" "$KB" "$OUT"
+  report=$(ls "$OUT"/*kb-hygiene-report.org)
+  grep -q "Conflict files: 1" "$report"
+}