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"
+}