@onlooker-community/ecosystem 0.34.0 → 0.43.0

package/test/bats/cartographer-events.bats

@@ -0,0 +1,267 @@
+#!/usr/bin/env bats
+
+# Validates every emitted cartographer.* event against @onlooker-community/schema.
+#
+# Both cartographer payloads were off-contract from the day the plugin shipped:
+# the published schema described a design that was never built, so every event
+# failed validation and emit_safe swallowed the failure with `|| true`. Findings
+# still landed on disk, so /cartographer looked healthy and nothing surfaced the
+# loss. Nothing here drove a real payload through validation, which is why the
+# two sides could drift that far apart (ecosystem-q4d).
+#
+# So these tests build their payloads with the same
+# cartographer_issue_found_payload / cartographer_audit_complete_payload the
+# audit calls — not a copy of them. A copy would be free to drift in exactly the
+# way the schema did.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/cartographer"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+	export CLAUDE_SESSION_ID="bats-session-$$"
+
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/cartographer-events.sh"
+}
+
+# Skip when the installed schema predates the corrected cartographer payloads.
+# The old definitions required issue_type/file_path; asserting against them
+# would be asserting the bug.
+_require_cartographer_schema() {
+	if ! grep -q "finding_hash" \
+		"${REPO_ROOT}/node_modules/@onlooker-community/schema/schemas/payload/plugins-memory.json" 2>/dev/null; then
+		skip "installed @onlooker-community/schema predates the corrected cartographer payloads"
+	fi
+}
+
+# Skip when the installed schema predates cartographer.issue.resolved (2.15.0).
+_require_resolution_schema() {
+	if ! grep -q "cartographer.issue.resolved" \
+		"${REPO_ROOT}/node_modules/@onlooker-community/schema/schemas/payload/plugins-memory.json" 2>/dev/null; then
+		skip "installed @onlooker-community/schema predates cartographer.issue.resolved"
+	fi
+}
+
+_validate_latest_event() {
+	local last
+	last=$(tail -n 1 "$ONLOOKER_EVENTS_LOG")
+	[ -n "$last" ] || return 1
+	printf '%s' "$last" | ONLOOKER_DIR="$ONLOOKER_DIR" \
+		node "${REPO_ROOT}/scripts/lib/onlooker-event.mjs" validate >/dev/null
+}
+
+# Valid 26-char Crockford Base32 ULID (no I, L, O, or U).
+AUDIT_ID="01J0000000000000000000AB34"
+
+# A finding record in the shape the analysis phases produce, which is what
+# run_emit reads out of ALL_FINDINGS.
+_finding() {
+	local type="${1:-undocumented_entity}" severity="${2:-warning}"
+	local file_a="${3:-CLAUDE.md}" file_b="${4:-null}"
+	jq -cn --arg t "$type" --arg s "$severity" --arg a "$file_a" --argjson b "$file_b" \
+		'{type: $t, severity: $s, file_a: $a, file_b: $b,
+		  description: "fixture finding", suggested_fix: "document it"}'
+}
+
+@test "cartographer.issue.found validates for a single-file finding" {
+	_require_cartographer_schema
+	cartographer_emit_event "cartographer.issue.found" \
+		"$(cartographer_issue_found_payload "$AUDIT_ID" "abc123" "$(_finding)")"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "cartographer.issue.found validates for a two-file finding" {
+	_require_cartographer_schema
+	cartographer_emit_event "cartographer.issue.found" \
+		"$(cartographer_issue_found_payload "$AUDIT_ID" "abc123" \
+			"$(_finding contradiction error CLAUDE.md '"AGENTS.md"')")"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "every finding type the analysis phases produce validates" {
+	_require_cartographer_schema
+	local t
+	for t in contradiction stale_ref dead_rule scope_collision undocumented_entity; do
+		cartographer_emit_event "cartographer.issue.found" \
+			"$(cartographer_issue_found_payload "$AUDIT_ID" "hash-${t}" "$(_finding "$t")")" \
+			|| return 1
+		_validate_latest_event || return 1
+	done
+}
+
+@test "cartographer.audit.complete validates" {
+	_require_cartographer_schema
+	cartographer_emit_event "cartographer.audit.complete" \
+		"$(cartographer_audit_complete_payload "$AUDIT_ID" "session_start_first_run" 1 3 8420)"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "every trigger the hooks set validates" {
+	_require_cartographer_schema
+	local t
+	for t in session_start_first_run session_start_interval post_tool_use manual; do
+		cartographer_emit_event "cartographer.audit.complete" \
+			"$(cartographer_audit_complete_payload "$AUDIT_ID" "$t" 0 0 5)" || return 1
+		_validate_latest_event || return 1
+	done
+}
+
+# The emitted payload is the contract downstream reads, so assert on its
+# contents and not merely that it validated. finding_hash in particular is what
+# makes at-least-once delivery deduplicable (the plugin's ADR-003).
+@test "the emitted payload carries the fields consumers read" {
+	_require_cartographer_schema
+	cartographer_emit_event "cartographer.issue.found" \
+		"$(cartographer_issue_found_payload "$AUDIT_ID" "abc123" \
+			"$(_finding contradiction error CLAUDE.md '"AGENTS.md"')")"
+
+	grep '"event_type":"cartographer.issue.found"' "$ONLOOKER_EVENTS_LOG" \
+		| jq -e --arg a "$AUDIT_ID" '
+			.payload.audit_id == $a
+			and .payload.finding_hash == "abc123"
+			and .payload.finding_type == "contradiction"
+			and .payload.severity == "error"
+			and .payload.affected_files == ["CLAUDE.md", "AGENTS.md"]
+		' >/dev/null
+}
+
+@test "a single-file finding carries exactly one affected file" {
+	_require_cartographer_schema
+	cartographer_emit_event "cartographer.issue.found" \
+		"$(cartographer_issue_found_payload "$AUDIT_ID" "abc123" "$(_finding)")"
+
+	tail -n 1 "$ONLOOKER_EVENTS_LOG" \
+		| jq -e '.payload.affected_files == ["CLAUDE.md"]' >/dev/null
+}
+
+@test "the retired pre-implementation vocabulary no longer validates" {
+	_require_cartographer_schema
+	# Guards the direction of the fix: if someone "restores" the old schema,
+	# this is the test that objects.
+	run cartographer_emit_event "cartographer.issue.found" \
+		'{"issue_type":"orphaned_plugin","file_path":"CLAUDE.md","severity":"warning"}'
+	[ "$status" -ne 0 ]
+}
+
+# A finding that reaches the emit phase without a usable .type is a bug in
+# whichever analysis phase produced it. The builder used to paper over that with
+# finding_type "unknown" — a value no schema admits — so the payload was
+# rejected, emit_safe swallowed the rejection with `|| true`, and the finding
+# landed on disk with nothing on the bus. Failing here instead puts the problem
+# in audit.log where an operator can read it (ecosystem-ci0).
+#
+# Empty string is covered alongside null and absent because jq's `//` treats ""
+# as present, so it slipped past the old fallback and produced a payload just as
+# unvalidatable as "unknown", by a different route.
+@test "a finding with no usable type is rejected rather than defaulted" {
+	local shape
+	for shape in '{}' '{"type":null}' '{"type":""}'; do
+		run cartographer_issue_found_payload "$AUDIT_ID" "abc123" \
+			"$(jq -cn --argjson s "$shape" \
+				'$s + {severity:"warning", file_a:"CLAUDE.md", description:"d"}')"
+		[ "$status" -ne 0 ] || return 1
+	done
+}
+
+# End-to-end statement of the symptom. Note this one does NOT discriminate the
+# builder fix — before it, the schema rejected "unknown" downstream and the bus
+# stayed empty for that reason instead. What it guards is the schema side: it
+# fails if anyone ever admits "unknown" into the finding_type enum, which was
+# the tempting cheap fix ci0 rejected.
+@test "a typeless finding puts nothing on the bus" {
+	_require_cartographer_schema
+	run cartographer_emit_event "cartographer.issue.found" \
+		"$(cartographer_issue_found_payload "$AUDIT_ID" "abc123" \
+			'{"severity":"warning","file_a":"CLAUDE.md","description":"d"}')"
+	[ "$status" -ne 0 ] || return 1
+	[ ! -s "$ONLOOKER_EVENTS_LOG" ]
+}
+
+@test "the builder names the rejected finding on stderr" {
+	# Returning non-zero is not enough on its own — emit_safe appends this
+	# stream to audit.log, so the message is what an operator actually reads.
+	run cartographer_issue_found_payload "$AUDIT_ID" "abc123" \
+		'{"severity":"warning","file_a":"CLAUDE.md","description":"d"}'
+	[ "$status" -ne 0 ] || return 1
+	[[ "$output" == *"abc123"* ]] || return 1
+	[[ "$output" == *"carries no type"* ]]
+}
+
+# A full audit retires findings it stopped observing, and that never reached the
+# bus: a consumer reading only the log saw every finding ever opened and none
+# ever closed (ecosystem-w2i).
+@test "cartographer.issue.resolved validates" {
+	_require_resolution_schema
+	cartographer_emit_event "cartographer.issue.resolved" \
+		"$(cartographer_issue_resolved_payload "$AUDIT_ID" "abc123")"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+# Symmetry with issue.found is the whole point: the same hash opens and closes a
+# finding, so a consumer can hold open/closed state from the log alone.
+@test "the resolved payload carries the hash a consumer closes on" {
+	_require_resolution_schema
+	cartographer_emit_event "cartographer.issue.resolved" \
+		"$(cartographer_issue_resolved_payload "$AUDIT_ID" "abc123")"
+	tail -n 1 "$ONLOOKER_EVENTS_LOG" \
+		| jq -e --arg a "$AUDIT_ID" \
+			'.payload.audit_id == $a and .payload.finding_hash == "abc123"' >/dev/null
+}
+
+@test "the resolved payload builder rejects missing arguments" {
+	run cartographer_issue_resolved_payload "" "abc123"
+	[ "$status" -ne 0 ] || return 1
+	run cartographer_issue_resolved_payload "$AUDIT_ID" ""
+	[ "$status" -ne 0 ]
+}
+
+@test "audit.complete carries resolved_finding_count when the sweep ran" {
+	_require_resolution_schema
+	cartographer_emit_event "cartographer.audit.complete" \
+		"$(cartographer_audit_complete_payload "$AUDIT_ID" "manual" 0 2 500 3)"
+	run _validate_latest_event
+	[ "$status" -eq 0 ] || return 1
+	tail -n 1 "$ONLOOKER_EVENTS_LOG" \
+		| jq -e '.payload.resolved_finding_count == 3' >/dev/null
+}
+
+# A targeted or partial run skips the sweep entirely, so it must report no count
+# rather than a zero that reads as "swept, found nothing to retire".
+@test "audit.complete omits resolved_finding_count when the sweep was skipped" {
+	_require_resolution_schema
+	cartographer_emit_event "cartographer.audit.complete" \
+		"$(cartographer_audit_complete_payload "$AUDIT_ID" "post_tool_use" 1 1 20)"
+	run _validate_latest_event
+	[ "$status" -eq 0 ] || return 1
+	tail -n 1 "$ONLOOKER_EVENTS_LOG" \
+		| jq -e '.payload | has("resolved_finding_count") | not' >/dev/null
+}
+
+@test "payload builders reject missing arguments" {
+	run cartographer_issue_found_payload "" "abc123" "$(_finding)"
+	[ "$status" -ne 0 ] || return 1
+	run cartographer_issue_found_payload "$AUDIT_ID" "" "$(_finding)"
+	[ "$status" -ne 0 ] || return 1
+	run cartographer_audit_complete_payload ""
+	[ "$status" -ne 0 ]
+}
+
+@test "emission fails on unknown event type" {
+	run cartographer_emit_event "cartographer.no.such.event" '{"audit_id":"x"}'
+	[ "$status" -ne 0 ]
+}
+
+@test "cartographer_emit_event returns 1 when payload is empty" {
+	run cartographer_emit_event "cartographer.issue.found" ""
+	[ "$status" -ne 0 ]
+}

package/test/bats/cartographer-filter.bats

@@ -0,0 +1,169 @@
+#!/usr/bin/env bats
+
+# Unit coverage for the --type and --scope narrowing.
+#
+# Both flags were documented in SKILL.md while run-audit.sh read neither, so a
+# user who passed them got a silent full audit (ecosystem-9og). The end-to-end
+# proof that they now change what runs lives in cartographer-run-audit.bats;
+# this file pins the decision logic those tests depend on.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/cartographer"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/cartographer-filter.sh"
+}
+
+# ── Type validity ────────────────────────────────────────────────────────────
+
+@test "every documented finding type is accepted" {
+	local t
+	for t in contradiction dead_rule stale_ref scope_collision undocumented_entity; do
+		cartographer_filter_valid_type "$t" || return 1
+	done
+}
+
+# The published schema's finding_type enum and this list are the same five
+# values; a type valid here that the schema rejects would emit nothing.
+@test "the accepted types match the schema enum exactly" {
+	local schema="${REPO_ROOT}/node_modules/@onlooker-community/schema/schemas/payload/plugins-memory.json"
+	[ -f "$schema" ] || skip "schema package not installed"
+	local from_schema from_lib
+	from_schema=$(jq -r '.["$defs"]["cartographer.issue.found"].properties.finding_type.enum //
+	                     .definitions["cartographer.issue.found"].properties.finding_type.enum
+	                     | sort | join(" ")' "$schema")
+	from_lib=$(printf '%s\n' $CARTOGRAPHER_FINDING_TYPES | sort | tr '\n' ' ' | sed 's/ $//')
+	[ "$from_schema" = "$from_lib" ]
+}
+
+@test "an unknown type is rejected" {
+	run cartographer_filter_valid_type "not_a_type"
+	[ "$status" -ne 0 ]
+}
+
+@test "an empty type is rejected, so callers must check before filtering" {
+	run cartographer_filter_valid_type ""
+	[ "$status" -ne 0 ]
+}
+
+# ── Which analyzers run ──────────────────────────────────────────────────────
+
+@test "no filter runs every analyzer" {
+	local a
+	for a in contradiction stale_ref scope_collision undocumented_entity; do
+		cartographer_filter_wants "$a" "" || return 1
+	done
+}
+
+@test "a type filter runs only its own analyzer" {
+	cartographer_filter_wants "stale_ref" "stale_ref" || return 1
+	run cartographer_filter_wants "scope_collision" "stale_ref"
+	[ "$status" -ne 0 ] || return 1
+	run cartographer_filter_wants "undocumented_entity" "stale_ref"
+	[ "$status" -ne 0 ] || return 1
+	run cartographer_filter_wants "contradiction" "stale_ref"
+	[ "$status" -ne 0 ]
+}
+
+# contradiction and dead_rule come out of one LLM pass, so either request must
+# run that analyzer. Skipping it for dead_rule would silently produce nothing.
+@test "dead_rule runs the contradiction analyzer" {
+	cartographer_filter_wants "contradiction" "dead_rule"
+}
+
+@test "asking for dead_rule still skips the unrelated analyzers" {
+	run cartographer_filter_wants "stale_ref" "dead_rule"
+	[ "$status" -ne 0 ] || return 1
+	run cartographer_filter_wants "undocumented_entity" "dead_rule"
+	[ "$status" -ne 0 ]
+}
+
+# ── Filtering the results ────────────────────────────────────────────────────
+
+FINDINGS='[{"type":"contradiction","file_a":"a"},{"type":"dead_rule","file_a":"b"}]'
+
+@test "no filter passes findings through untouched" {
+	run cartographer_filter_findings "$FINDINGS" ""
+	[ "$output" = "$FINDINGS" ]
+}
+
+# The shared LLM pass returns both types, so the unrequested one is dropped here.
+@test "the co-emitted type is dropped from the results" {
+	run bash -c "source '${PLUGIN_ROOT}/scripts/lib/cartographer-filter.sh'
+	             cartographer_filter_findings '$FINDINGS' 'dead_rule' | jq -c '[.[].type]'"
+	[ "$output" = '["dead_rule"]' ]
+}
+
+@test "filtering to the other co-emitted type keeps only it" {
+	run bash -c "source '${PLUGIN_ROOT}/scripts/lib/cartographer-filter.sh'
+	             cartographer_filter_findings '$FINDINGS' 'contradiction' | jq -c '[.[].type]'"
+	[ "$output" = '["contradiction"]' ]
+}
+
+@test "a type present in no finding yields an empty array, not an error" {
+	run cartographer_filter_findings "$FINDINGS" "stale_ref"
+	[ "$status" -eq 0 ] || return 1
+	[ "$output" = "[]" ]
+}
+
+@test "malformed findings json degrades to empty rather than aborting" {
+	run cartographer_filter_findings "not json" "stale_ref"
+	[ "$status" -eq 0 ] || return 1
+	[ "$output" = "[]" ]
+}
+
+# ── Scope ────────────────────────────────────────────────────────────────────
+
+FILES='["/repo/CLAUDE.md","/repo/plugins/tribunal/CLAUDE.md","/repo/plugins/echo/CLAUDE.md"]'
+
+@test "no scope passes the file list through untouched" {
+	run cartographer_filter_scope "$FILES" "/repo" ""
+	[ "$output" = "$FILES" ]
+}
+
+@test "a repo-relative scope keeps only files beneath it" {
+	run bash -c "source '${PLUGIN_ROOT}/scripts/lib/cartographer-filter.sh'
+	             cartographer_filter_scope '$FILES' '/repo' 'plugins/tribunal' | jq -c ."
+	[ "$output" = '["/repo/plugins/tribunal/CLAUDE.md"]' ]
+}
+
+@test "an absolute scope works too" {
+	run bash -c "source '${PLUGIN_ROOT}/scripts/lib/cartographer-filter.sh'
+	             cartographer_filter_scope '$FILES' '/repo' '/repo/plugins/echo' | jq -c ."
+	[ "$output" = '["/repo/plugins/echo/CLAUDE.md"]' ]
+}
+
+@test "a trailing slash on the scope does not change the match" {
+	run bash -c "source '${PLUGIN_ROOT}/scripts/lib/cartographer-filter.sh'
+	             cartographer_filter_scope '$FILES' '/repo' 'plugins/tribunal/' | jq -c 'length'"
+	[ "$output" = "1" ]
+}
+
+@test "a leading ./ on the scope does not change the match" {
+	run bash -c "source '${PLUGIN_ROOT}/scripts/lib/cartographer-filter.sh'
+	             cartographer_filter_scope '$FILES' '/repo' './plugins/tribunal' | jq -c 'length'"
+	[ "$output" = "1" ]
+}
+
+# A sibling whose name merely starts with the scope string is not inside it.
+# Prefix matching without the separator would pull plugins/echo-legacy into a
+# scope of plugins/echo.
+@test "a sibling sharing a name prefix is not swept in" {
+	local files='["/repo/plugins/echo/CLAUDE.md","/repo/plugins/echo-legacy/CLAUDE.md"]'
+	run bash -c "source '${PLUGIN_ROOT}/scripts/lib/cartographer-filter.sh'
+	             cartographer_filter_scope '$files' '/repo' 'plugins/echo' | jq -c ."
+	[ "$output" = '["/repo/plugins/echo/CLAUDE.md"]' ]
+}
+
+@test "scoping to an exact file path keeps that file" {
+	run bash -c "source '${PLUGIN_ROOT}/scripts/lib/cartographer-filter.sh'
+	             cartographer_filter_scope '$FILES' '/repo' 'CLAUDE.md' | jq -c ."
+	[ "$output" = '["/repo/CLAUDE.md"]' ]
+}
+
+@test "a scope matching nothing yields an empty list" {
+	run cartographer_filter_scope "$FILES" "/repo" "does/not/exist"
+	[ "$output" = "[]" ]
+}

package/test/bats/cartographer-lock.bats

@@ -89,8 +89,8 @@ teardown() {
     cartographer_lock_release '${BATS_TEST_TMPDIR}/x.lock' && echo RELEASE_OK
   "
   [ "$status" -eq 0 ]
-  [[ "$output" == *"SOURCED_OK"* ]]
-  [[ "$output" == *"ACQUIRE_FAILED"* ]]
-  [[ "$output" == *"RELEASE_OK"* ]]
+  [[ "$output" == *"SOURCED_OK"* ]] || return 1
+  [[ "$output" == *"ACQUIRE_FAILED"* ]] || return 1
+  [[ "$output" == *"RELEASE_OK"* ]] || return 1
   [[ "$output" == *"locking disabled"* ]]
 }

package/test/bats/cartographer-omission.bats

@@ -0,0 +1,202 @@
+#!/usr/bin/env bats
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/cartographer"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/cartographer-omission.sh"
+
+  FIXTURE_REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "${FIXTURE_REPO}/plugins/alpha" \
+           "${FIXTURE_REPO}/plugins/beta" \
+           "${FIXTURE_REPO}/skills/solo"
+  DOC="${FIXTURE_REPO}/CLAUDE.md"
+  printf '# Doc\nThe alpha plugin does things.\n' > "$DOC"
+  CORPUS=$(jq -n --arg f "$DOC" '[$f]')
+}
+
+@test "flags an entity whose name appears nowhere in the corpus" {
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["plugins/*/"]' '[]' 20)
+  [[ "$(printf '%s' "$out" | jq -r 'length')" == "1" ]] || return 1
+  [[ "$(printf '%s' "$out" | jq -r '.[0].excerpt_a')" == "beta" ]] || return 1
+  [ "$(printf '%s' "$out" | jq -r '.[0].type')" = "undocumented_entity" ]
+}
+
+@test "does not flag an entity the corpus mentions" {
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["plugins/*/"]' '[]' 20)
+  [ "$(printf '%s' "$out" | jq -r '[.[] | select(.excerpt_a == "alpha")] | length')" = "0" ]
+}
+
+@test "finding carries the entity as file_a and a null file_b" {
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["plugins/*/"]' '[]' 20)
+  [[ "$(printf '%s' "$out" | jq -r '.[0].file_a')" == "${FIXTURE_REPO}/plugins/beta" ]] || return 1
+  [[ "$(printf '%s' "$out" | jq -r '.[0].file_b')" == "null" ]] || return 1
+  [ "$(printf '%s' "$out" | jq -r '.[0].severity')" = "warning" ]
+}
+
+@test "word boundary: a longer word containing the name does not count as a mention" {
+  printf '# Doc\nWe do a lot of counseling here.\n' > "$DOC"
+  mkdir -p "${FIXTURE_REPO}/plugins/counsel"
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["plugins/*/"]' '[]' 20)
+  [ "$(printf '%s' "$out" | jq -r '[.[] | select(.excerpt_a == "counsel")] | length')" = "1" ]
+}
+
+@test "word boundary: a hyphenated name is not matched inside a longer hyphenated token" {
+  printf '# Doc\nSee my-list-prompt-rules-thing for details.\n' > "$DOC"
+  mkdir -p "${FIXTURE_REPO}/skills/list-prompt-rules"
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["skills/*/"]' '[]' 20)
+  [ "$(printf '%s' "$out" | jq -r '[.[] | select(.excerpt_a == "list-prompt-rules")] | length')" = "1" ]
+}
+
+@test "word boundary: a name bounded by slashes counts as a mention" {
+  printf '# Doc\nSee plugins/beta/ for details.\n' > "$DOC"
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["plugins/*/"]' '[]' 20)
+  [ "$(printf '%s' "$out" | jq -r '[.[] | select(.excerpt_a == "beta")] | length')" = "0" ]
+}
+
+@test "exclude filters a matched path by substring" {
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["plugins/*/","skills/*/"]' '["skills/"]' 20)
+  [[ "$(printf '%s' "$out" | jq -r 'length')" == "1" ]] || return 1
+  [ "$(printf '%s' "$out" | jq -r '.[0].excerpt_a')" = "beta" ]
+}
+
+@test "max_findings caps the result and reports the drop count on stderr" {
+  local out err
+  err="${BATS_TEST_TMPDIR}/err.txt"
+  out=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["plugins/*/","skills/*/"]' '[]' 1 2>"$err")
+  [[ "$(printf '%s' "$out" | jq -r 'length')" == "1" ]] || return 1
+  grep -q "1 candidate" "$err"
+}
+
+@test "a glob matching nothing yields an empty array" {
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["nonexistent/*/"]' '[]' 20)
+  [ "$out" = "[]" ]
+}
+
+@test "an empty corpus yields an empty array rather than flagging everything" {
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    '[]' "$FIXTURE_REPO" '["plugins/*/"]' '[]' 20)
+  [ "$out" = "[]" ]
+}
+
+@test "the same entity produces an identical finding hash across two runs" {
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/cartographer-analyze.sh"
+  local a b h1 h2
+  a=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["plugins/*/"]' '[]' 20)
+  b=$(cartographer_analyze_undocumented_entity \
+    "$CORPUS" "$FIXTURE_REPO" '["plugins/*/"]' '[]' 20)
+  h1=$(cartographer_finding_hash "undocumented_entity" \
+    "$(printf '%s' "$a" | jq -r '.[0].file_a')" \
+    "$(printf '%s' "$a" | jq -r '.[0].excerpt_a')" "" "")
+  h2=$(cartographer_finding_hash "undocumented_entity" \
+    "$(printf '%s' "$b" | jq -r '.[0].file_a')" \
+    "$(printf '%s' "$b" | jq -r '.[0].excerpt_a')" "" "")
+  [[ -n "$h1" ]] || return 1
+  [ "$h1" = "$h2" ]
+}
+
+@test "flags an entity under a repo root whose path contains a space" {
+  # BATS_TEST_TMPDIR itself never contains a space, which is exactly why this
+  # was missed — build a fixture one level under it that does.
+  local spaced_repo="${BATS_TEST_TMPDIR}/my repo"
+  mkdir -p "${spaced_repo}/plugins/alpha" "${spaced_repo}/plugins/beta"
+  local doc="${spaced_repo}/CLAUDE.md"
+  printf '# Doc\nThe alpha plugin does things.\n' > "$doc"
+  local corpus
+  corpus=$(jq -n --arg f "$doc" '[$f]')
+
+  local out
+  out=$(cartographer_analyze_undocumented_entity \
+    "$corpus" "$spaced_repo" '["plugins/*/"]' '[]' 20)
+  [ "$(printf '%s' "$out" | jq -r '[.[] | select(.excerpt_a == "beta")] | length')" = "1" ]
+}
+
+# Stubs `claude` so the three LLM phases make no real call, then runs a full
+# audit. Any extra env the caller needs is exported before calling this.
+_run_audit() {
+  local stub="${BATS_TEST_TMPDIR}/bin"
+  mkdir -p "$stub"
+  printf '#!/usr/bin/env bash\ncat >/dev/null\nprintf "[]"\n' > "${stub}/claude"
+  chmod +x "${stub}/claude"
+
+  PATH="${stub}:${PATH}" \
+  CARTOGRAPHER_DIR="${BATS_TEST_TMPDIR}/state" \
+  CARTOGRAPHER_REPO_ROOT="$FIXTURE_REPO" \
+  CARTOGRAPHER_TRIGGER="manual" \
+  CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT" \
+    bash "${PLUGIN_ROOT}/scripts/run-audit.sh"
+}
+
+# run_emit writes findings with a bare `jq`, which pretty-prints — the file
+# contains `"type": "undocumented_entity"` with a space. Parse rather than grep.
+_findings_of_type() {
+  local dir="${BATS_TEST_TMPDIR}/state/findings"
+  local count=0 f
+  [[ -d "$dir" ]] || { printf '0'; return 0; }
+  for f in "$dir"/*.json; do
+    [[ -e "$f" ]] || continue
+    if [[ "$(jq -r '.type // ""' "$f" 2>/dev/null)" == "undocumented_entity" ]]; then
+      count=$(( count + 1 ))
+    fi
+  done
+  printf '%s' "$count"
+}
+
+# Names of every undocumented_entity finding on disk, sorted, space-separated.
+_findings_named() {
+  local dir="${BATS_TEST_TMPDIR}/state/findings"
+  local names=() f
+  [[ -d "$dir" ]] || return 0
+  for f in "$dir"/*.json; do
+    [[ -e "$f" ]] || continue
+    if [[ "$(jq -r '.type // ""' "$f" 2>/dev/null)" == "undocumented_entity" ]]; then
+      names+=("$(jq -r '.excerpt_a' "$f")")
+    fi
+  done
+  printf '%s' "$(printf '%s\n' "${names[@]+"${names[@]}"}" | sort | tr '\n' ' ' | sed 's/ $//')"
+}
+
+@test "integration: a full audit records the undocumented entities on disk" {
+  # alpha is documented; beta and solo are not, and the default globs cover
+  # both plugins/ and skills/. Assert identity, not just count — a bare count
+  # passes just as happily on two findings for the same entity.
+  _run_audit
+  [ "$(_findings_named)" = "beta solo" ]
+}
+
+@test "integration: a targeted post-write audit records no undocumented entity" {
+  export CARTOGRAPHER_TARGET_FILE="$DOC"
+  _run_audit
+  [ "$(_findings_of_type)" = "0" ]
+}
+
+@test "integration: enabled=false suppresses the phase" {
+  mkdir -p "${FIXTURE_REPO}/.claude"
+  printf '%s\n' '{"cartographer":{"undocumented_entity":{"enabled":false}}}' \
+    > "${FIXTURE_REPO}/.claude/settings.json"
+  _run_audit
+  [ "$(_findings_of_type)" = "0" ]
+}