@onlooker-community/ecosystem 0.34.0 → 0.43.0

package/plugins/cartographer/README.md

@@ -14,6 +14,7 @@ Every other Onlooker plugin is reactive. Cartographer is the exception.
 | `dead_rule` | A rule fully subsumed by a more specific rule elsewhere |
 | `stale_ref` | A reference to a file path, tool, or command that no longer exists |
 | `scope_collision` | A project rule that duplicates or silently overrides a global `~/.claude/CLAUDE.md` rule |
+| `undocumented_entity` | Something that exists on disk — a plugin, a skill — that no instruction file mentions |
 
 ## Installation
 
@@ -42,7 +43,7 @@ Findings appear in the next `/cartographer` invocation or in any event log consu
 /cartographer --verbose    # show all known findings (no bus events)
 /cartographer --status     # running state + last completion time
 /cartographer --force      # kill running audit and restart
-/cartographer --phase=contradiction   # single-phase audit
+/cartographer --type=stale_ref        # one finding type; skips the other analyzers
 /cartographer --scope=src/            # scoped to a subdirectory
 ```
 
@@ -74,6 +75,43 @@ All options are optional. Defaults shown:
 
 **Note:** Overriding `exclude_paths` replaces the entire list. Repeat the defaults plus your additions if you want to extend rather than replace.
 
+### Detecting omissions
+
+Every other check reads the instruction files and tests what it finds against
+the filesystem. `undocumented_entity` runs the other way: it enumerates
+entities on disk and flags any whose name appears in no instruction file. That
+is the one kind of drift the other checks structurally cannot see — something
+absent produces no reference to follow. The mention check is case-sensitive,
+so `plugins/foo/` documented only as "Foo" is still flagged as undocumented.
+
+This phase only runs as part of a full audit (SessionStart or manual
+`/cartographer`) — it is skipped on the targeted post-write audit that runs
+after you edit an instruction file, so editing `CLAUDE.md` never produces an
+omission finding on its own.
+
+```json
+{
+  "cartographer": {
+    "undocumented_entity": {
+      "enabled": true,
+      "globs": ["plugins/*/", "skills/*/"],
+      "exclude": [],
+      "max_findings": 20
+    }
+  }
+}
+```
+
+`globs` are relative to the repository root, and a glob matching nothing is
+simply inert — the defaults do nothing in a repository without those
+directories. The list is deliberately opt-in: most of a repository has no
+business being named in `CLAUDE.md`, so only classes where you expect the
+documentation to be *complete* belong here.
+
+**Note:** as with `exclude_paths`, overriding `globs` or `exclude` replaces the
+entire list rather than extending it. Repeat the defaults alongside your
+additions if you mean to extend.
+
 ## Privacy
 
 - All analysis uses `claude -p` via your existing Claude Code session — no separate API key, no new data recipient.
@@ -92,10 +130,27 @@ All options are optional. Defaults shown:
 └── dedup/                 # empty sentinel per emitted finding hash
 ```
 
+## Finding lifecycle
+
+A finding is born `resolved: false` and refreshed on every audit that observes it again. A **full** audit that completes without a failed phase then retires anything it did not observe: absence is the evidence that the drift is gone, so those records get `resolved: true` and a `resolved_at` stamp, and `/cartographer` stops rendering them. `/cartographer --verbose` still lists them, tagged `[RESOLVED]`, so you can confirm a fix took.
+
+Two runs deliberately retire nothing, because neither looked widely enough for absence to mean anything:
+
+- **Targeted post-write audits** evaluate a single file, so nearly every stored finding is absent for reasons unrelated to being fixed.
+- **Partial runs** (any phase timed out or errored) produce no findings for the phase that failed, which is indistinguishable from its findings being gone.
+
+Resolution is not terminal. The dedup sentinel outlives it, so drift that is reintroduced returns as a *known* finding — that path reopens the record (`resolved: false`, `resolved_at` cleared) rather than filing a new one, keeping `first_seen_at` intact. Without that, a recurring finding would stay hidden forever.
+
 ## Event delivery
 
 `cartographer.issue.found` events are delivered at-least-once. If the audit process crashes between emitting an event and writing the dedup sentinel, the finding is re-emitted once on the next run. Downstream consumers must deduplicate on `payload.finding_hash`.
 
+`cartographer.issue.resolved` carries the same `finding_hash`, so a consumer can close the finding it opened and hold open/closed state from the log alone. It is emitted only by a run that looked everywhere: a targeted audit sees a single file and a run with a failed phase sees an incomplete corpus, so neither can treat a finding's absence as evidence its drift is gone.
+
+The payload carries no timestamp of its own. The envelope's required `timestamp` is the resolution time, since the event is emitted from the sweep that flips the record.
+
+`cartographer.audit.complete` reports `resolved_finding_count` for the same reason and under the same condition — a run that skipped the sweep omits the field entirely rather than reporting `0`, which would read as "swept, retired nothing".
+
 ## Non-goals
 
 Cartographer will not:

package/plugins/cartographer/config.json

@@ -15,6 +15,12 @@
       "model": "claude-haiku-4-5-20251001",
       "max_output_tokens": 2048
     },
-    "exclude_paths": ["node_modules", ".git", "vendor", ".venv", "dist", ".next", ".nuxt", "build", "__pycache__"]
+    "exclude_paths": ["node_modules", ".git", "vendor", ".venv", "dist", ".next", ".nuxt", "build", "__pycache__"],
+    "undocumented_entity": {
+      "enabled": true,
+      "globs": ["plugins/*/", "skills/*/"],
+      "exclude": [],
+      "max_findings": 20
+    }
   }
 }

package/plugins/cartographer/scripts/hooks/cartographer-post-write.sh

@@ -66,18 +66,18 @@ export CARTOGRAPHER_TARGET_FILE="$CANONICAL"
 export CARTOGRAPHER_REPO_ROOT="$REPO_ROOT"
 export ONLOOKER_DIR
 
+# The launcher deliberately loads no config — see the matching note in
+# cartographer-session-start.sh. It execs run-audit.sh, which loads config once
+# for itself; anything loaded here is discarded by the exec, and could not have
+# resolved in the first place because PLUGIN_ROOT is not exported.
 if command -v setsid &>/dev/null; then
 	nohup setsid bash -c "
 	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
-	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
-	  cartographer_config_load \"$REPO_ROOT\"
 	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
 	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
 else
 	nohup bash -c "
 	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
-	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
-	  cartographer_config_load \"$REPO_ROOT\"
 	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
 	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
 fi

package/plugins/cartographer/scripts/hooks/cartographer-session-start.sh

@@ -68,18 +68,21 @@ export CARTOGRAPHER_TRIGGER="$TRIGGER"
 export CARTOGRAPHER_REPO_ROOT="$REPO_ROOT"
 export ONLOOKER_DIR
 
+# The launcher deliberately loads no config. It execs run-audit.sh, which
+# replaces the process, and the config lives in a plain shell variable that is
+# never exported — so anything loaded here is discarded a line later. It also
+# could not have worked: PLUGIN_ROOT is not exported (only CLAUDE_PLUGIN_ROOT
+# is), so cartographer-config.sh resolved config-loader.sh against an empty
+# prefix in this sub-shell and appended two lines of noise to audit.log on every
+# audit. run-audit.sh loads config once, for itself.
 if command -v setsid &>/dev/null; then
 	nohup setsid bash -c "
 	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
-	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
-	  cartographer_config_load \"$REPO_ROOT\"
 	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
 	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
 else
 	nohup bash -c "
 	  trap 'source \"$PLUGIN_ROOT/scripts/lib/cartographer-lock.sh\"; cartographer_lock_release \"$LOCK_FILE\"' EXIT
-	  source \"$PLUGIN_ROOT/scripts/lib/cartographer-config.sh\"
-	  cartographer_config_load \"$REPO_ROOT\"
 	  exec \"$PLUGIN_ROOT/scripts/run-audit.sh\"
 	" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1 &
 fi

package/plugins/cartographer/scripts/lib/cartographer-collect.sh

@@ -25,9 +25,16 @@ cartographer_collect_files() {
 	done < <(printf '%s' "$exclude_json" | jq -r '.[]' 2>/dev/null)
 
 	# Discover CLAUDE.md and AGENTS.md
+	#
+	# ${find_excludes[@]+"${find_excludes[@]}"} rather than "${find_excludes[@]}":
+	# under bash 3.2 (macOS system bash) with `set -u`, expanding a genuinely
+	# empty array with the plain form is an unbound-variable error, not an
+	# empty expansion — that's the case whenever exclude_json has zero entries
+	# (e.g. it is unset upstream, or a caller deliberately passes "[]"). The
+	# `+` form is the standard portable guard for bash <4.4.
 	find "$repo_root" -maxdepth "$max_depth" \
 		\( -name "CLAUDE.md" -o -name "AGENTS.md" \) \
-		"${find_excludes[@]}" \
+		${find_excludes[@]+"${find_excludes[@]}"} \
 		-type f 2>/dev/null
 
 	# Discover .claude/rules/*.md at repo level

package/plugins/cartographer/scripts/lib/cartographer-config.sh

@@ -78,3 +78,29 @@ cartographer_config_max_output_tokens_synthesis() {
 	v=$(cartographer_config_get '.cartographer.synthesis.max_output_tokens')
 	printf '%s' "${v:-2048}"
 }
+
+# ── undocumented_entity phase ──────────────────────────────────────────────────
+# Disk → doc detection. Unlike the other phases these are read inside the
+# analysis sub-shell rather than by the orchestrator; see run-audit.sh and
+# ecosystem-88v for why.
+
+cartographer_config_undocumented_enabled() {
+	local v
+	v=$(cartographer_config_get '.cartographer.undocumented_entity.enabled')
+	printf '%s' "${v:-true}"
+}
+
+cartographer_config_undocumented_globs() {
+	cartographer_config_get_json \
+		'.cartographer.undocumented_entity.globs // ["plugins/*/","skills/*/"]'
+}
+
+cartographer_config_undocumented_exclude() {
+	cartographer_config_get_json '.cartographer.undocumented_entity.exclude // []'
+}
+
+cartographer_config_undocumented_max_findings() {
+	local v
+	v=$(cartographer_config_get '.cartographer.undocumented_entity.max_findings')
+	printf '%s' "${v:-20}"
+}

package/plugins/cartographer/scripts/lib/cartographer-events.sh

@@ -44,6 +44,96 @@ _cartographer_session_id() {
 	printf 'unknown'
 }
 
+# Build the cartographer.issue.found payload for one finding record.
+#
+# Lives here rather than inline in run_emit so the test suite drives the same
+# construction production does. Two independent descriptions of one payload is
+# precisely how the published schema came to document events no code had ever
+# emitted; a single builder means a test that passes is evidence about the real
+# emission path, not about a copy of it.
+#
+# Usage: cartographer_issue_found_payload <audit_id> <finding_hash> <finding_json>
+cartographer_issue_found_payload() {
+	local audit_id="${1:-}" finding_hash="${2:-}" finding="${3:-}"
+	[[ -z "$audit_id" || -z "$finding_hash" || -z "$finding" ]] && return 1
+
+	local ftype fseverity ffile_a ffile_b fdesc
+	# A finding with no usable type is malformed — the analysis phase that
+	# produced it has a bug. This used to default to "unknown", a value no
+	# schema admits, so the payload was built, rejected at emit, and the
+	# rejection swallowed by the caller's emit_safe: the finding reached disk
+	# and nothing reached the bus. Failing here puts it in audit.log instead,
+	# where an operator can read it (ecosystem-ci0).
+	#
+	# `// ""` collapses absent, null, and empty into one check. jq's `//`
+	# treats "" as present, so an empty type would otherwise slip through and
+	# produce a payload just as unvalidatable as "unknown", by another route.
+	ftype=$(printf '%s' "$finding" | jq -r '.type // ""')
+	if [[ -z "$ftype" ]]; then
+		printf 'cartographer-events: finding %s carries no type; refusing to emit issue.found\n' \
+			"$finding_hash" >&2
+		return 1
+	fi
+	fseverity=$(printf '%s' "$finding" | jq -r '.severity // "warning"')
+	ffile_a=$(printf '%s' "$finding" | jq -r '.file_a // ""')
+	ffile_b=$(printf '%s' "$finding" | jq -r '.file_b // null')
+	fdesc=$(printf '%s' "$finding" | jq -r '.description // ""')
+
+	jq -n \
+		--arg audit_id "$audit_id" \
+		--arg finding_hash "$finding_hash" \
+		--arg finding_type "$ftype" \
+		--arg severity "$fseverity" \
+		--argjson affected_files "$(jq -n --arg a "$ffile_a" --arg b "$ffile_b" \
+			'if $b == "null" or $b == "" then [$a] else [$a,$b] end')" \
+		--arg summary "$fdesc" \
+		'{"audit_id":$audit_id,"finding_hash":$finding_hash,"finding_type":$finding_type,"severity":$severity,"affected_files":$affected_files,"summary":$summary}'
+}
+
+# Build the cartographer.issue.resolved payload for a retired finding.
+#
+# Deliberately just the pair: the envelope already carries a required timestamp
+# set at emit time, and this is emitted from the sweep that flips the record, so
+# a payload-level resolved_at would duplicate it while being free to disagree —
+# the record stores epoch seconds, the envelope ISO 8601. The schema rejects the
+# field for that reason (onlooker-community/schema#50).
+#
+# Usage: cartographer_issue_resolved_payload <audit_id> <finding_hash>
+cartographer_issue_resolved_payload() {
+	local audit_id="${1:-}" finding_hash="${2:-}"
+	[[ -z "$audit_id" || -z "$finding_hash" ]] && return 1
+
+	jq -n \
+		--arg audit_id "$audit_id" \
+		--arg finding_hash "$finding_hash" \
+		'{"audit_id":$audit_id,"finding_hash":$finding_hash}'
+}
+
+# Build the cartographer.audit.complete payload for a finished run.
+#
+# resolved_count is optional and omitted from the payload when empty. That is
+# the difference between "swept and retired nothing" and "never swept": a
+# targeted or partial run cannot treat a finding's absence as evidence, so it
+# must report no count rather than a zero that reads as the former.
+#
+# Usage: cartographer_audit_complete_payload <audit_id> <trigger> <new_count> <total_count> <duration_ms> [resolved_count]
+cartographer_audit_complete_payload() {
+	local audit_id="${1:-}" trigger="${2:-}"
+	local new_count="${3:-0}" total_count="${4:-0}" duration_ms="${5:-0}"
+	local resolved_count="${6:-}"
+	[[ -z "$audit_id" ]] && return 1
+
+	jq -n \
+		--arg audit_id "$audit_id" \
+		--arg trigger "$trigger" \
+		--argjson new_finding_count "$new_count" \
+		--argjson total_finding_count "$total_count" \
+		--argjson duration_ms "$duration_ms" \
+		--arg resolved "$resolved_count" \
+		'{"audit_id":$audit_id,"trigger":$trigger,"new_finding_count":$new_finding_count,"total_finding_count":$total_finding_count,"duration_ms":$duration_ms}
+		 + (if $resolved == "" then {} else {"resolved_finding_count": ($resolved|tonumber)} end)'
+}
+
 cartographer_emit_event() {
 	local event_type="${1:-}"
 	local payload="${2:-}"

package/plugins/cartographer/scripts/lib/cartographer-filter.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# cartographer-filter.sh — narrow an audit to one finding type or one subtree.
+#
+# SKILL.md documented a --phase flag and a --scope flag that run-audit.sh never
+# read, so both silently ran a full audit (ecosystem-9og). The vocabulary was
+# wrong too: --phase listed finding TYPES, while the pipeline's phases are
+# discover/extract/relate/synthesize/emit. The flag is --type here for that
+# reason — it narrows what the audit looks FOR, not which stage runs.
+#
+# The five types do not map one-to-one onto analyzer calls:
+#
+#   contradiction        \_ one LLM pass emits either type, so neither can be
+#   dead_rule            /  requested without running the other
+#   stale_ref            — its own call
+#   scope_collision      — its own call
+#   undocumented_entity  — its own call
+#
+# So narrowing works in two steps: skip the analyzers that cannot produce the
+# requested type, then drop any findings the surviving analyzers produced that
+# were not asked for. Skipping is where the savings are — each analyzer skipped
+# is an LLM call not made.
+
+CARTOGRAPHER_FINDING_TYPES="contradiction dead_rule stale_ref scope_collision undocumented_entity"
+
+# True when a type filter is set and valid.
+#
+# An unrecognized value is rejected rather than silently matching nothing: a
+# typo that quietly produced an empty audit would look exactly like a clean
+# repo, which is the failure this whole issue is about.
+#
+# Usage: cartographer_filter_valid_type <type>
+cartographer_filter_valid_type() {
+	local want="${1:-}"
+	[[ -z "$want" ]] && return 1
+	local t
+	for t in $CARTOGRAPHER_FINDING_TYPES; do
+		[[ "$t" == "$want" ]] && return 0
+	done
+	return 1
+}
+
+# True when the analyzer should run under the active filter.
+#
+# An empty filter means no filter, so everything runs. The contradiction
+# analyzer answers to both of the types it can emit.
+#
+# Usage: cartographer_filter_wants <analyzer> <type_filter>
+#   analyzer: contradiction | stale_ref | scope_collision | undocumented_entity
+cartographer_filter_wants() {
+	local analyzer="${1:-}" filter="${2:-}"
+	[[ -z "$filter" ]] && return 0
+	[[ -z "$analyzer" ]] && return 1
+
+	if [[ "$analyzer" == "contradiction" ]]; then
+		[[ "$filter" == "contradiction" || "$filter" == "dead_rule" ]]
+		return
+	fi
+	[[ "$analyzer" == "$filter" ]]
+}
+
+# Drop findings whose type was not requested.
+#
+# Only the contradiction analyzer can return a type other than the one asked
+# for, but filtering the whole set is simpler than special-casing it and stays
+# correct if an analyzer gains a second output type later.
+#
+# Usage: cartographer_filter_findings <findings_json> <type_filter>
+cartographer_filter_findings() {
+	local findings="${1:-[]}" filter="${2:-}"
+	if [[ -z "$filter" ]]; then
+		printf '%s' "$findings"
+		return 0
+	fi
+	printf '%s' "$findings" \
+		| jq -c --arg t "$filter" '[.[] | select(.type == $t)]' 2>/dev/null \
+		|| printf '[]'
+}
+
+# Restrict a discovered-file list to those under a subtree.
+#
+# The scope narrows which instruction files are ANALYZED; it deliberately does
+# not become the repo root, because stale_ref resolves path-like tokens against
+# the real root and would otherwise report every path outside the scope as
+# broken.
+#
+# A scope matching nothing yields an empty list, which is a legitimate answer —
+# the caller decides whether that is worth reporting.
+#
+# Usage: cartographer_filter_scope <files_json> <repo_root> <scope_path>
+cartographer_filter_scope() {
+	local files="${1:-[]}" repo_root="${2:-}" scope="${3:-}"
+	if [[ -z "$scope" ]]; then
+		printf '%s' "$files"
+		return 0
+	fi
+
+	# Accept a repo-relative scope or an absolute one.
+	local abs="$scope"
+	[[ "$abs" != /* ]] && abs="${repo_root%/}/${scope#./}"
+	abs="${abs%/}"
+
+	printf '%s' "$files" \
+		| jq -c --arg p "$abs" '[.[] | select(. == $p or startswith($p + "/"))]' 2>/dev/null \
+		|| printf '[]'
+}

package/plugins/cartographer/scripts/lib/cartographer-omission.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# cartographer-omission.sh — disk → doc detection.
+#
+# Every other analysis phase starts from the text of the instruction files and
+# tests what it finds against the filesystem. This one runs the other way: it
+# enumerates entities on disk and checks each is mentioned somewhere in the
+# corpus. An entity nothing names produces no token for stale_ref to extract
+# and no rule for contradiction to compare, which is why omissions were
+# previously invisible to every phase.
+#
+# Detection is a grep — no model call. A model would only help judge whether an
+# omission MATTERS, which is a sharper question than the drift that motivated
+# this. See docs/superpowers/specs/2026-08-16-cartographer-undocumented-entity-design.md
+#
+# Usage:
+#   cartographer_analyze_undocumented_entity <files_json> <repo_root> \
+#       <globs_json> <exclude_json> <max_findings>
+#
+# Prints a JSON array of findings on stdout in the same shape the analyzers in
+# cartographer-analyze.sh return, so run_synthesize merges it without special
+# handling. Diagnostics go to stderr, which run-audit.sh appends to audit.log.
+
+# Word-boundary mention test.
+#
+# Boundaries are hand-rolled rather than \b because entity names contain
+# hyphens, and \b treats '-' as a non-word character: \blist-prompt-rules\b
+# would also match inside "my-list-prompt-rules-thing". Bounding on
+# [^A-Za-z0-9_-] instead means a hyphenated name matches only when genuinely
+# standalone, while a name inside a path ("plugins/beta/") still counts.
+_cartographer_name_mentioned() {
+	local name="$1"
+	local files_json="$2"
+
+	local escaped
+	escaped=$(printf '%s' "$name" | sed 's/[][\.*^$(){}?+|\\]/\\&/g')
+
+	local fpath
+	while IFS= read -r fpath; do
+		[[ -z "$fpath" || ! -f "$fpath" ]] && continue
+		if grep -qE "(^|[^A-Za-z0-9_-])${escaped}([^A-Za-z0-9_-]|\$)" "$fpath" 2>/dev/null; then
+			return 0
+		fi
+	done < <(printf '%s' "$files_json" | jq -r '.[]' 2>/dev/null)
+	return 1
+}
+
+cartographer_analyze_undocumented_entity() {
+	local files_json="${1:-[]}"
+	local repo_root="${2:?repo_root required}"
+	local globs_json="${3:-[]}"
+	local exclude_json="${4:-[]}"
+	local max_findings="${5:-20}"
+
+	# An empty corpus cannot document anything, so every entity would look
+	# undocumented. Refuse rather than emit a burst of false findings that the
+	# emit phase would dedup-sentinel and never re-evaluate.
+	local corpus_count
+	corpus_count=$(printf '%s' "$files_json" | jq 'length' 2>/dev/null || printf '0')
+	[[ "${corpus_count:-0}" -eq 0 ]] && { printf '[]'; return 0; }
+
+	local findings="[]"
+	local emitted=0 dropped=0
+	local root="${repo_root%/}"
+
+	# nullglob so an unmatched pattern expands to nothing rather than to itself.
+	# Restore the prior setting — this library is sourced, not run.
+	local had_nullglob=0
+	shopt -q nullglob && had_nullglob=1
+	shopt -s nullglob
+
+	local glob match
+	while IFS= read -r glob; do
+		[[ -z "$glob" ]] && continue
+		# shellcheck disable=SC2086 # $glob unquoted on purpose: this is the glob
+		# expansion. ${root} IS quoted — a repo path containing a space must not
+		# word-split before the glob expands, or the match silently finds nothing.
+		for match in "${root}"/$glob; do
+			[[ -e "$match" ]] || continue
+
+			local trimmed="${match%/}"
+			local name relpath
+			name=$(basename "$trimmed")
+			relpath="${trimmed#"${root}"/}"
+
+			local excluded=0 excl
+			while IFS= read -r excl; do
+				[[ -z "$excl" ]] && continue
+				[[ "$relpath" == *"$excl"* ]] && { excluded=1; break; }
+			done < <(printf '%s' "$exclude_json" | jq -r '.[]' 2>/dev/null)
+			[[ "$excluded" -eq 1 ]] && continue
+
+			_cartographer_name_mentioned "$name" "$files_json" && continue
+
+			if [[ "$emitted" -ge "$max_findings" ]]; then
+				dropped=$(( dropped + 1 ))
+				continue
+			fi
+
+			local finding
+			finding=$(jq -n \
+				--arg fa "$trimmed" \
+				--arg n "$name" \
+				--arg rp "$relpath" \
+				'{
+					type: "undocumented_entity",
+					severity: "warning",
+					file_a: $fa,
+					excerpt_a: $n,
+					file_b: null,
+					excerpt_b: null,
+					description: ($n + " exists at " + $rp
+						+ " but is not mentioned in any instruction file."),
+					suggested_fix: ("Document " + $n
+						+ " in CLAUDE.md, or exclude its path from cartographer.undocumented_entity.")
+				}')
+			findings=$(printf '%s' "$findings" | jq --argjson f "$finding" '. + [$f]')
+			emitted=$(( emitted + 1 ))
+		done
+	done < <(printf '%s' "$globs_json" | jq -r '.[]' 2>/dev/null)
+
+	[[ "$had_nullglob" -eq 0 ]] && shopt -u nullglob
+
+	# Say what was dropped. A silent truncation reads as "this is everything".
+	if [[ "$dropped" -gt 0 ]]; then
+		printf 'undocumented_entity: capped at %s findings, %s candidate(s) dropped\n' \
+			"$max_findings" "$dropped" >&2
+	fi
+
+	printf '%s' "$findings"
+}

package/plugins/cartographer/scripts/lib/cartographer-resolve.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# cartographer-resolve.sh — retire findings whose drift is gone.
+#
+# A finding is written once to findings/<hash>.json and re-observed on every
+# later audit, which refreshes last_seen_at. Nothing ever marked one absent, so
+# fixing the drift a finding reported did not retire the finding — it rendered
+# forever. The record already carried resolved:false from birth; the field
+# existed, the loop that flips it did not.
+#
+# Absence is the evidence: the audit knows every finding it observed this run,
+# so anything in the store whose last_seen_at predates this run's start was not
+# observed and its drift is gone.
+#
+# That inference is only sound when the run actually looked everywhere, which is
+# what the two guards below protect.
+
+# Refresh a finding that was observed again this run.
+#
+# Usage: cartographer_refresh_finding <finding_file> <now>
+#
+# Reopening matters as much as the timestamp. The dedup sentinel outlives
+# resolution, so drift that is fixed and then reintroduced arrives here rather
+# than down the new-finding path. Leaving resolved:true would keep a live
+# finding hidden from the renderer forever — a silent false negative, and a
+# worse failure than the stale findings this module exists to retire.
+cartographer_refresh_finding() {
+	local finding_file="${1:-}" now="${2:-}"
+	[[ -z "$finding_file" || -z "$now" ]] && return 1
+	[[ -f "$finding_file" ]] || return 1
+
+	local updated
+	updated=$(jq --argjson ts "$now" \
+		'.last_seen_at = $ts | .resolved = false | del(.resolved_at)' \
+		"$finding_file" 2>/dev/null) || return 1
+	[[ -z "$updated" ]] && return 1
+
+	printf '%s\n' "$updated" >"${finding_file}.tmp" || return 1
+	mv -f "${finding_file}.tmp" "$finding_file"
+}
+
+# Whether this run looked at enough for absence to mean anything.
+#
+# Two ways it does not. A targeted post-write audit evaluates a single file, so
+# almost every stored finding is "unobserved" for reasons that have nothing to
+# do with being fixed — letting it resolve would wipe the store on every edit.
+# And a phase that timed out or errored contributes no findings, which is
+# indistinguishable from its findings being gone.
+#
+# Named rather than inlined because run_emit needs the same answer to decide
+# whether cartographer.audit.complete may report a resolved count at all. Two
+# copies of this condition is precisely the kind of divergence that has bitten
+# this plugin before.
+#
+# Usage: cartographer_resolution_is_sound <target_file> <phases_failed>
+cartographer_resolution_is_sound() {
+	local target_file="${1:-}" phases_failed="${2:-0}"
+	[[ -z "$target_file" && "$phases_failed" -eq 0 ]]
+}
+
+# Mark findings not observed by this audit as resolved.
+#
+# Usage:
+#   cartographer_resolve_absent_findings <findings_dir> <cutoff_ts> \
+#                                        <target_file> <phases_failed_count> \
+#                                        [now] [on_resolved]
+#
+# on_resolved, when given, is the name of a function called once per retired
+# finding with its hash. Its stdout is discarded; see the call site below.
+#
+# cutoff_ts is the audit's start time: a finding observed this run had its
+# last_seen_at refreshed to at-or-after it, so a record older than it was not
+# observed. The comparison is strict (<), which errs toward leaving a finding
+# open when the timestamps collide — a stale finding is visible and correctable,
+# an incorrectly retired one is silent.
+#
+# Prints the number of findings newly resolved.
+cartographer_resolve_absent_findings() {
+	local findings_dir="${1:-}" cutoff_ts="${2:-}"
+	local target_file="${3:-}" phases_failed="${4:-0}"
+	local now="${5:-}"
+	local on_resolved="${6:-}"
+	[[ -z "$now" ]] && now=$(date +%s)
+
+	[[ -z "$findings_dir" || -z "$cutoff_ts" ]] && return 1
+	if [[ ! -d "$findings_dir" ]]; then
+		printf '0'
+		return 0
+	fi
+
+	# Both guards live in the predicate. A run that fails either one retires
+	# nothing and announces nothing — announcing a resolution the run did not
+	# establish tells every consumer to close a finding that is still live.
+	if ! cartographer_resolution_is_sound "$target_file" "$phases_failed"; then
+		printf '0'
+		return 0
+	fi
+
+	local resolved=0 f updated
+	for f in "$findings_dir"/*.json; do
+		[[ -f "$f" ]] || continue
+		# Emits nothing when the record is already resolved or was seen this
+		# run, so an unchanged record is never rewritten and never counted.
+		updated=$(jq --argjson cutoff "$cutoff_ts" --argjson now "$now" '
+			if .resolved == true then empty
+			elif ((.last_seen_at // 0) < $cutoff) then . + {resolved: true, resolved_at: $now}
+			else empty end
+		' "$f" 2>/dev/null) || continue
+		[[ -z "$updated" ]] && continue
+		printf '%s\n' "$updated" >"${f}.tmp" || continue
+		mv -f "${f}.tmp" "$f" || continue
+		resolved=$(( resolved + 1 ))
+
+		# Announce inside the guarded loop, so a run that must not resolve also
+		# cannot announce. The emitter is injected rather than sourced: this
+		# module stays pure data, and a test can pass a stub without dragging
+		# the event bus in behind it.
+		#
+		# stdout is the count channel — the caller reads it through a command
+		# substitution — so the emitter is redirected away from it. That is also
+		# why announcing works at all here despite the subshell: appending to
+		# the event log is a filesystem effect, and unlike a variable it
+		# survives.
+		if [[ -n "$on_resolved" ]]; then
+			local fhash
+			fhash=$(printf '%s' "$updated" | jq -r '.finding_hash // ""')
+			[[ -z "$fhash" ]] && fhash=$(basename "$f" .json)
+			"$on_resolved" "$fhash" >/dev/null || true
+		fi
+	done
+
+	printf '%d' "$resolved"
+}