From b0140951ebe0f0c2d33a868a2d1cda2eafd29044 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Wed, 10 Jun 2026 18:21:15 -0500
Subject: feat(kb): monthly hygiene report for agent KB nodes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 scripts/tests/kb-hygiene.bats | 87 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 scripts/tests/kb-hygiene.bats

(limited to 'scripts/tests')

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"
+}
-- 
cgit v1.2.3