@onlooker-community/ecosystem 0.34.1 → 0.43.0

package/plugins/cartographer/scripts/run-audit.sh

@@ -8,7 +8,7 @@
 #   1. discover   — collect all auditable files
 #   2. extract    — per-file content hash (incremental cache key)
 #   3. relate     — contradiction + dead_rule analysis (LLM)
-#   4. synthesize — stale_ref + scope_collision + finding hash computation
+#   4. synthesize — stale_ref + scope_collision + undocumented_entity + hash
 #   5. emit       — persist findings atomically, emit events for new findings
 #
 # Environment:
@@ -28,13 +28,18 @@ source "$PLUGIN_ROOT/scripts/lib/cartographer-config.sh"
 source "$PLUGIN_ROOT/scripts/lib/cartographer-ulid.sh"
 source "$PLUGIN_ROOT/scripts/lib/cartographer-project-key.sh"
 source "$PLUGIN_ROOT/scripts/lib/cartographer-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-resolve.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-filter.sh"
 source "$PLUGIN_ROOT/scripts/lib/cartographer-collect.sh"
 source "$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh"
+source "$PLUGIN_ROOT/scripts/lib/cartographer-omission.sh"
 
 CARTOGRAPHER_DIR="${CARTOGRAPHER_DIR:?CARTOGRAPHER_DIR must be set}"
 TRIGGER="${CARTOGRAPHER_TRIGGER:-manual}"
 TARGET_FILE="${CARTOGRAPHER_TARGET_FILE:-}"
 REPO_ROOT="${CARTOGRAPHER_REPO_ROOT:-$(pwd)}"
+TYPE_FILTER="${CARTOGRAPHER_TYPE_FILTER:-}"
+SCOPE_PATH="${CARTOGRAPHER_SCOPE_PATH:-}"
 AUDIT_ID=$(cartographer_ulid)
 START_TS=$(date +%s)
 
@@ -49,6 +54,16 @@ PHASES_COMPLETED=()
 PHASES_FAILED=()
 ALL_FINDINGS="[]"
 
+# Load config before any accessor runs. Without this every accessor below falls
+# through to its hardcoded default, so exclude_paths, the timeouts, the models,
+# and the token caps were all silently unconfigurable — the orchestrator was the
+# one place that never loaded (ecosystem-88v).
+#
+# This is the single load for the whole audit. The analysis sub-shells take
+# their settings as positional parameters and read no config of their own, so
+# the values resolved here are the ones that take effect everywhere.
+cartographer_config_load "$REPO_ROOT"
+
 _phase_timeout=$(cartographer_config_phase_timeout)
 _total_timeout=$(cartographer_config_total_timeout)
 log() { printf '[cartographer] %s\n' "$*" >>"$CARTOGRAPHER_DIR/audit.log" 2>&1; }
@@ -59,11 +74,36 @@ _model_synthesis=$(cartographer_config_model_synthesis)
 _max_tokens_extraction=$(cartographer_config_max_output_tokens_extraction)
 _max_tokens_synthesis=$(cartographer_config_max_output_tokens_synthesis)
 _exclude_json=$(cartographer_config_exclude_paths)
+_undocumented_enabled=$(cartographer_config_undocumented_enabled)
+_undocumented_globs=$(cartographer_config_undocumented_globs)
+_undocumented_exclude=$(cartographer_config_undocumented_exclude)
+_undocumented_max=$(cartographer_config_undocumented_max_findings)
 
 emit_safe() {
 	cartographer_emit_event "$1" "$2" 2>>"$CARTOGRAPHER_DIR/audit.log" || true
 }
 
+# Announce one finding the resolution sweep retired.
+#
+# Passed to cartographer_resolve_absent_findings by name rather than called
+# after it, so the announcement happens inside the sweep's own guards — a run
+# that must not resolve cannot announce either. Handing over a function name
+# also keeps cartographer-resolve.sh free of any dependency on the event bus.
+_emit_resolved() {
+	emit_safe "cartographer.issue.resolved" \
+		"$(cartographer_issue_resolved_payload "$AUDIT_ID" "$1")"
+}
+
+# Reject an unrecognized type rather than filtering everything away. An empty
+# audit is indistinguishable from a clean repo, so a typo would read as good
+# news — the same class of silent-nothing this flag was filed for.
+if [[ -n "$TYPE_FILTER" ]] && ! cartographer_filter_valid_type "$TYPE_FILTER"; then
+	log "error: unknown type filter '${TYPE_FILTER}' (expected one of: ${CARTOGRAPHER_FINDING_TYPES})"
+	exit 1
+fi
+[[ -n "$TYPE_FILTER" ]] && log "filter type=${TYPE_FILTER}"
+[[ -n "$SCOPE_PATH" ]] && log "filter scope=${SCOPE_PATH}"
+
 # ── Phase 1: Discover ──────────────────────────────────────────────────────────
 run_discover() {
 	log "phase=discover starting"
@@ -82,6 +122,14 @@ run_discover() {
 		GLOBAL_FILES=$(printf '%s\n' "$raw_global" | grep -v '^$' | jq -R . | jq -s .)
 	fi
 
+	# Scope narrows what gets analyzed, not what the repo root is: stale_ref
+	# resolves path tokens against the real root, and re-rooting would make
+	# every reference outside the scope look broken.
+	if [[ -n "$SCOPE_PATH" ]]; then
+		DISCOVERED_FILES=$(cartographer_filter_scope \
+			"$DISCOVERED_FILES" "$REPO_ROOT" "$SCOPE_PATH")
+	fi
+
 	local file_count
 	file_count=$(printf '%s' "$DISCOVERED_FILES" | jq 'length')
 	log "phase=discover files=${file_count}"
@@ -119,11 +167,19 @@ run_extract() {
 # ── Phase 3: Relate (contradiction + dead_rule) ────────────────────────────────
 run_relate() {
 	log "phase=relate starting"
+
+	# One LLM pass emits both contradiction and dead_rule, so asking for either
+	# runs it and the unwanted type is filtered out of the result below.
+	if ! cartographer_filter_wants "contradiction" "$TYPE_FILTER"; then
+		log "phase=relate skipped by type filter"
+		RELATE_FINDINGS="[]"
+		PHASES_COMPLETED+=("relate")
+		return 0
+	fi
+
 	local findings
 	findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
-		"source '$PLUGIN_ROOT/scripts/lib/cartographer-config.sh'
-		 source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
-		 cartographer_config_load '$REPO_ROOT'
+		"source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
 		 cartographer_analyze_contradiction '$DISCOVERED_FILES' \
 		   '$_model_extraction' '$_max_tokens_extraction' '$_phase_timeout'" \
 		2>>"$CARTOGRAPHER_DIR/audit.log") || {
@@ -131,7 +187,7 @@ run_relate() {
 		PHASES_FAILED+=("relate")
 		return 1
 	}
-	RELATE_FINDINGS="${findings:-[]}"
+	RELATE_FINDINGS=$(cartographer_filter_findings "${findings:-[]}" "$TYPE_FILTER")
 	local count
 	count=$(printf '%s' "$RELATE_FINDINGS" | jq 'length' 2>/dev/null || printf '0')
 	log "phase=relate findings=${count}"
@@ -142,22 +198,39 @@ run_relate() {
 run_synthesize() {
 	log "phase=synthesize starting"
 
-	local stale_findings scope_findings
-	stale_findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
-		"source '$PLUGIN_ROOT/scripts/lib/cartographer-config.sh'
-		 source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
-		 cartographer_config_load '$REPO_ROOT'
-		 cartographer_analyze_stale_ref '$DISCOVERED_FILES' '$REPO_ROOT' \
-		   '$_model_synthesis' '$_max_tokens_synthesis' '$_phase_timeout'" \
-		2>>"$CARTOGRAPHER_DIR/audit.log") || stale_findings="[]"
-
-	scope_findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
-		"source '$PLUGIN_ROOT/scripts/lib/cartographer-config.sh'
-		 source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
-		 cartographer_config_load '$REPO_ROOT'
-		 cartographer_analyze_scope_collision '$GLOBAL_FILES' '$DISCOVERED_FILES' \
-		   '$_model_synthesis' '$_max_tokens_synthesis' '$_phase_timeout'" \
-		2>>"$CARTOGRAPHER_DIR/audit.log") || scope_findings="[]"
+	# Each analyzer skipped under a type filter is an LLM call not made, which
+	# is where the flag earns its keep.
+	local stale_findings="[]" scope_findings="[]"
+	if cartographer_filter_wants "stale_ref" "$TYPE_FILTER"; then
+		stale_findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
+			"source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
+			 cartographer_analyze_stale_ref '$DISCOVERED_FILES' '$REPO_ROOT' \
+			   '$_model_synthesis' '$_max_tokens_synthesis' '$_phase_timeout'" \
+			2>>"$CARTOGRAPHER_DIR/audit.log") || stale_findings="[]"
+	fi
+
+	if cartographer_filter_wants "scope_collision" "$TYPE_FILTER"; then
+		scope_findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
+			"source '$PLUGIN_ROOT/scripts/lib/cartographer-analyze.sh'
+			 cartographer_analyze_scope_collision '$GLOBAL_FILES' '$DISCOVERED_FILES' \
+			   '$_model_synthesis' '$_max_tokens_synthesis' '$_phase_timeout'" \
+			2>>"$CARTOGRAPHER_DIR/audit.log") || scope_findings="[]"
+	fi
+
+	# Disk → doc. Skipped on targeted post-write audits: DISCOVERED_FILES is a
+	# single file there, so grepping it for every entity name would report
+	# nearly the whole enumeration as undocumented, and the emit phase would
+	# dedup-sentinel those false findings permanently. scope_collision already
+	# no-ops on targeted runs for the same reason.
+	local omission_findings="[]"
+	if [[ -z "$TARGET_FILE" && "$_undocumented_enabled" == "true" ]] \
+		&& cartographer_filter_wants "undocumented_entity" "$TYPE_FILTER"; then
+		omission_findings=$($_TIMEOUT_CMD "$_phase_timeout" bash -c \
+			"source '$PLUGIN_ROOT/scripts/lib/cartographer-omission.sh'
+			 cartographer_analyze_undocumented_entity '$DISCOVERED_FILES' '$REPO_ROOT' \
+			   '$_undocumented_globs' '$_undocumented_exclude' '$_undocumented_max'" \
+			2>>"$CARTOGRAPHER_DIR/audit.log") || omission_findings="[]"
+	fi
 
 	# Merge all raw findings
 	local raw_all
@@ -165,7 +238,8 @@ run_synthesize() {
 		--argjson relate "${RELATE_FINDINGS:-[]}" \
 		--argjson stale "${stale_findings:-[]}" \
 		--argjson scope "${scope_findings:-[]}" \
-		'$relate + $stale + $scope')
+		--argjson omission "${omission_findings:-[]}" \
+		'$relate + $stale + $scope + $omission')
 
 	# Add finding_hash to each finding
 	ALL_FINDINGS="[]"
@@ -213,14 +287,11 @@ run_emit() {
 		now=$(date +%s)
 
 		if [[ -f "$dedup_sentinel" ]]; then
-			# Known finding — update last_seen_at atomically, no bus event
+			# Known finding — refresh it atomically, no bus event. Refreshing
+			# also reopens it; see cartographer_refresh_finding for why that is
+			# load-bearing rather than tidiness.
 			(( known_count++ )) || true
-			if [[ -f "$finding_file" ]]; then
-				local updated
-				updated=$(jq --argjson ts "$now" '.last_seen_at=$ts' "$finding_file" 2>/dev/null) || true
-				[[ -n "$updated" ]] && printf '%s\n' "$updated" >"${finding_file}.tmp" \
-					&& mv -f "${finding_file}.tmp" "$finding_file"
-			fi
+			cartographer_refresh_finding "$finding_file" "$now" || true
 		else
 			# New finding — write file atomically, emit bus event, then mark dedup
 			local with_ts
@@ -229,22 +300,20 @@ run_emit() {
 			printf '%s\n' "$with_ts" >"${finding_file}.tmp"
 			mv -f "${finding_file}.tmp" "$finding_file"
 
-			local ftype fseverity ffile_a ffile_b fdesc
-			ftype=$(printf '%s' "$finding" | jq -r '.type // "unknown"')
-			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 // ""')
-
-			emit_safe "cartographer.issue.found" "$(jq -n \
-				--arg audit_id "$AUDIT_ID" \
-				--arg finding_hash "$fhash" \
-				--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}')"
+			# Branch on the builder rather than passing its output straight
+			# to emit_safe. A typeless finding makes it return non-zero, and
+			# an unchecked substitution would hand emit_safe an empty payload
+			# that cartographer_emit_event rejects silently — relocating the
+			# silence this fix exists to end (ecosystem-ci0). Its stderr is
+			# appended to the same audit.log emit_safe writes to, because the
+			# substitution runs before emit_safe and escapes that redirect.
+			local found_payload
+			if found_payload=$(cartographer_issue_found_payload \
+				"$AUDIT_ID" "$fhash" "$finding" 2>>"$CARTOGRAPHER_DIR/audit.log"); then
+				emit_safe "cartographer.issue.found" "$found_payload"
+			else
+				log "emit: no issue.found for ${fhash} — finding carries no type"
+			fi
 
 			touch "$dedup_sentinel"
 			(( new_count++ )) || true
@@ -253,6 +322,23 @@ run_emit() {
 
 	log "phase=emit new=${new_count} known=${known_count}"
 
+	# Retire findings this run did not observe. Guarded inside against targeted
+	# audits and partial runs, both of which see too little to treat absence as
+	# evidence the drift is gone.
+	local resolved_count
+	resolved_count=$(cartographer_resolve_absent_findings \
+		"$FINDINGS_DIR" "$START_TS" "$TARGET_FILE" "${#PHASES_FAILED[@]}" "" _emit_resolved)
+	log "phase=emit resolved=${resolved_count}"
+
+	# Only a run that actually swept may report a count. A targeted or partial
+	# run leaves the field off entirely rather than reporting 0, which would
+	# read as "swept, found nothing to retire". This asks the same predicate the
+	# sweep guards on, so the two cannot drift apart on what the run proved.
+	local resolved_arg=""
+	if cartographer_resolution_is_sound "$TARGET_FILE" "${#PHASES_FAILED[@]}"; then
+		resolved_arg="$resolved_count"
+	fi
+
 	local end_ts duration_ms total_count
 	end_ts=$(date +%s)
 	duration_ms=$(( (end_ts - START_TS) * 1000 ))
@@ -265,20 +351,17 @@ run_emit() {
 		--arg trigger "$TRIGGER" \
 		--argjson new_finding_count "$new_count" \
 		--argjson known_finding_count "$known_count" \
+		--argjson resolved_finding_count "$resolved_count" \
 		--argjson total_finding_count "$total_count" \
 		--argjson duration_ms "$duration_ms" \
 		--argjson phases_completed "$(printf '%s\n' "${PHASES_COMPLETED[@]}" | jq -R . | jq -s .)" \
 		--argjson phases_failed "$(printf '%s\n' "${PHASES_FAILED[@]:-}" | jq -R . | jq -s .)" \
-		'{"audit_id":$audit_id,"trigger":$trigger,"new_finding_count":$new_finding_count,"known_finding_count":$known_finding_count,"total_finding_count":$total_finding_count,"duration_ms":$duration_ms,"phases_completed":$phases_completed,"phases_failed":$phases_failed}' \
+		'{"audit_id":$audit_id,"trigger":$trigger,"new_finding_count":$new_finding_count,"known_finding_count":$known_finding_count,"resolved_finding_count":$resolved_finding_count,"total_finding_count":$total_finding_count,"duration_ms":$duration_ms,"phases_completed":$phases_completed,"phases_failed":$phases_failed}' \
 		>"${run_file}.tmp" && mv -f "${run_file}.tmp" "$run_file"
 
-	emit_safe "cartographer.audit.complete" "$(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" \
-		'{"audit_id":$audit_id,"trigger":$trigger,"new_finding_count":$new_finding_count,"total_finding_count":$total_finding_count,"duration_ms":$duration_ms}')"
+	emit_safe "cartographer.audit.complete" \
+		"$(cartographer_audit_complete_payload \
+			"$AUDIT_ID" "$TRIGGER" "$new_count" "$total_count" "$duration_ms" "$resolved_arg")"
 
 	PHASES_COMPLETED+=("emit")
 }

package/plugins/cartographer/skills/cartographer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cartographer
-description: Audit CLAUDE.md, AGENTS.md, and .claude/rules/ instruction files for contradictions, stale references, dead rules, and scope collisions. Runs a full audit in the foreground (with lock). Use when the user explicitly invokes /cartographer, or when they want immediate feedback after editing an instruction file. Supports --scope, --phase, --verbose, --status, and --force flags.
+description: Audit CLAUDE.md, AGENTS.md, and .claude/rules/ instruction files for contradictions, stale references, dead rules, scope collisions, and entities no instruction file mentions. Runs a full audit in the foreground (with lock). Use when the user explicitly invokes /cartographer, or when they want immediate feedback after editing an instruction file. Supports --scope, --type, --verbose, --status, and --force flags.
 ---
 
 # Cartographer Skill
@@ -55,14 +55,15 @@ After the audit completes, read findings and render them to the conversation gro
 
 ### `/cartographer --verbose` — all findings
 
-Shows ALL known findings (new + previously seen) from `$CARTOGRAPHER_DIR/findings/`. Does NOT re-emit bus events — renders to in-conversation output only.
+Shows ALL known findings (new + previously seen) from `$CARTOGRAPHER_DIR/findings/`, including ones already resolved — that is what makes this the verbose view. Resolved findings are tagged so "did my fix take?" is answerable here. Does NOT re-emit bus events — renders to in-conversation output only.
 
 ```bash
 echo "## Known Cartographer Findings"
 echo ""
 for f in "$CARTOGRAPHER_DIR/findings/"*.json; do
   [[ -f "$f" ]] || continue
-  jq -r '"**[\(.severity | ascii_upcase)]** \(.type) — \(.description)\n  Files: \(.file_a // "n/a") / \(.file_b // "n/a")\n  Fix: \(.suggested_fix // "n/a")\n"' "$f" 2>/dev/null
+  jq -r '(if .resolved == true then "[RESOLVED] " else "" end) as $r |
+    "\($r)**[\(.severity | ascii_upcase)]** \(.type) — \(.description)\n  Files: \(.file_a // "n/a") / \(.file_b // "n/a")\n  Fix: \(.suggested_fix // "n/a")\n"' "$f" 2>/dev/null
 done
 ```
 
@@ -86,7 +87,10 @@ fi
 
 runs=$(ls "$CARTOGRAPHER_DIR/runs/" 2>/dev/null | wc -l | tr -d ' ')
 total=$(ls "$CARTOGRAPHER_DIR/findings/" 2>/dev/null | wc -l | tr -d ' ')
-echo "Total findings on disk: $total"
+open=$(cat "$CARTOGRAPHER_DIR/findings/"*.json 2>/dev/null \
+  | jq -s '[.[] | select(.resolved != true)] | length' 2>/dev/null || echo 0)
+echo "Open findings: $open"
+echo "Total findings on disk: $total (includes resolved)"
 echo "Audit runs recorded: $runs"
 ```
 
@@ -107,18 +111,37 @@ fi
 # Then proceed as a normal full audit
 ```
 
-### `/cartographer --phase=<phase>` — single phase
+### `/cartographer --type=<type>` — single finding type
 
-Runs only one analysis phase: `contradiction`, `stale_ref`, `dead_rule`, or `scope_collision`.
-Pass `CARTOGRAPHER_PHASE_FILTER` to run-audit.sh (the script checks this env var and skips other phases).
+Narrows the audit to one finding type: `contradiction`, `dead_rule`, `stale_ref`, `scope_collision`, or `undocumented_entity`. Export `CARTOGRAPHER_TYPE_FILTER` before running.
+
+```bash
+export CARTOGRAPHER_TYPE_FILTER="stale_ref"
+```
+
+Analyzers that cannot produce the requested type are skipped entirely, so this is cheaper than a full audit — each skipped analyzer is an LLM call not made. Useful for re-checking one class of drift after fixing it without paying for the rest.
+
+One caveat, because the saving is not uniform: `contradiction` and `dead_rule` come out of a single LLM pass, so asking for either runs that pass and discards the other type from the results. Requesting one of those two costs the same as running both; the other three types are genuinely skippable.
+
+An unrecognized type is an error rather than a filter that matches nothing — an empty audit looks exactly like a clean repo, so a typo would read as good news.
 
 ### `/cartographer --scope=<path>` — scoped audit
 
-Limits discovery to files under `<path>`. Set `CARTOGRAPHER_SCOPE_PATH` before running.
+Limits analysis to instruction files under `<path>`, relative to the repo root or absolute. Export `CARTOGRAPHER_SCOPE_PATH` before running.
+
+```bash
+export CARTOGRAPHER_SCOPE_PATH="plugins/tribunal"
+```
+
+The scope narrows which files are analyzed; it does not become the repo root. `stale_ref` resolves path-like tokens against the real root, and re-rooting would report every reference outside the scope as broken.
+
+Both flags compose, and both apply to manual runs only — the SessionStart and PostToolUse hooks always run unfiltered.
 
 ## Rendering Findings
 
-After a manual audit completes, render findings grouped by severity:
+After a manual audit completes, render findings grouped by severity. Resolved
+findings are skipped — a finding whose drift the user already fixed must stop
+appearing here, or the advice to fix it never stops being given:
 
 ```bash
 echo "## Cartographer Findings"
@@ -129,6 +152,7 @@ for severity in error warning informational; do
   output=""
   for f in "$CARTOGRAPHER_DIR/findings/"*.json; do
     [[ -f "$f" ]] || continue
+    jq -e '.resolved != true' "$f" >/dev/null 2>&1 || continue
     fsev=$(jq -r '.severity // "warning"' "$f" 2>/dev/null)
     [[ "$fsev" != "$severity" ]] && continue
     (( count++ )) || true

package/plugins/librarian/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "librarian",
-  "version": "0.7.1",
+  "version": "0.13.2",
   "description": "Consolidation layer between archivist's per-session artifacts and the user's durable typed memory store. Detects which session decisions, dead-ends, and open questions deserve to live across sessions, classifies them into the user/feedback/project/reference types, and queues them as proposals for explicit confirmation. Auto-promotion is opt-in. Builds on the Onlooker ecosystem plugin.",
   "author": {
     "name": "Onlooker Community",

package/plugins/librarian/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## [0.13.2](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.13.1...librarian-v0.13.2) (2026-08-18)
+
+
+### Bug Fixes
+
+* **librarian:** put budget skips on the bus at last :satellite: ([#180](https://github.com/onlooker-community/ecosystem/issues/180)) ([bc91749](https://github.com/onlooker-community/ecosystem/commit/bc917495dab053cba825ea28ccdd1993fdacb3e9))
+* **librarian:** stop stage 5 from holding a session open :hourglass: ([#178](https://github.com/onlooker-community/ecosystem/issues/178)) ([4f12a1e](https://github.com/onlooker-community/ecosystem/commit/4f12a1ee25300e0dc372542814e0922df5dbd335))
+
+## [0.13.1](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.13.0...librarian-v0.13.1) (2026-08-15)
+
+
+### Bug Fixes
+
+* **librarian:** make proposals the sole dedup source, and say so :broom: ([#156](https://github.com/onlooker-community/ecosystem/issues/156)) ([729d9ea](https://github.com/onlooker-community/ecosystem/commit/729d9ea3e328c2734712cfc5adf556c6798334aa))
+
+## [0.13.0](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.12.1...librarian-v0.13.0) (2026-08-15)
+
+
+### Features
+
+* **tribunal,librarian:** make rubric weights and min_pass floors real :straight_ruler: ([#150](https://github.com/onlooker-community/ecosystem/issues/150)) ([f8f8e28](https://github.com/onlooker-community/ecosystem/commit/f8f8e28b60f6d13d5a2a54e26ca284137b77f99a))
+
+## [0.12.1](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.12.0...librarian-v0.12.1) (2026-08-14)
+
+
+### Bug Fixes
+
+* **librarian:** close four follow-up defects from the promotion epic :broom: ([#148](https://github.com/onlooker-community/ecosystem/issues/148)) ([895df74](https://github.com/onlooker-community/ecosystem/commit/895df7430fa8ba75976d38964d061c21bff785d3))
+
+## [0.12.0](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.11.0...librarian-v0.12.0) (2026-08-13)
+
+
+### Features
+
+* **librarian:** land judged lessons in the approved pool :package: ([#146](https://github.com/onlooker-community/ecosystem/issues/146)) ([f7adc72](https://github.com/onlooker-community/ecosystem/commit/f7adc7263a985d4cb7695b46d6f9dbab77dce587))
+
+## [0.11.0](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.10.0...librarian-v0.11.0) (2026-08-13)
+
+
+### Features
+
+* **librarian:** derive an author identity that cannot be linked across scopes :closed_lock_with_key: ([#144](https://github.com/onlooker-community/ecosystem/issues/144)) ([29b3042](https://github.com/onlooker-community/ecosystem/commit/29b3042ef6cd6e7582206cfea6fcf37ebe661021))
+
+## [0.10.0](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.9.0...librarian-v0.10.0) (2026-08-12)
+
+
+### Features
+
+* **librarian:** judge lessons before they leave the machine :balance_scale: ([#142](https://github.com/onlooker-community/ecosystem/issues/142)) ([a877527](https://github.com/onlooker-community/ecosystem/commit/a87752714961613b6b2bb768239c666f78d950f8))
+
+## [0.9.0](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.8.0...librarian-v0.9.0) (2026-08-11)
+
+
+### Features
+
+* **librarian:** let a human take back a lesson confirmation :leftwards_arrow_with_hook: ([#139](https://github.com/onlooker-community/ecosystem/issues/139)) ([a4c4ac8](https://github.com/onlooker-community/ecosystem/commit/a4c4ac8ed5b79f5596f4e22abd1d23a8b0d3e834))
+
+## [0.8.0](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.7.1...librarian-v0.8.0) (2026-08-11)
+
+
+### Features
+
+* **librarian:** let a human decide what leaves the machine :raised_hand: ([#137](https://github.com/onlooker-community/ecosystem/issues/137)) ([16d7673](https://github.com/onlooker-community/ecosystem/commit/16d76734833aee9c8818f84c1c1f704be4cdfc33))
+
 ## [0.7.1](https://github.com/onlooker-community/ecosystem/compare/librarian-v0.7.0...librarian-v0.7.1) (2026-08-10)
 
 

package/plugins/librarian/config.json

@@ -18,7 +18,36 @@
     },
     "lesson_transform": {
       "model": "claude-haiku-4-5-20251001",
-      "timeout_seconds": 20
+      "timeout_seconds": 20,
+      "total_budget_ms": 8000
+    },
+    "lesson_judging": {
+      "min_criterion_coverage": 0.6,
+      "rubrics": [
+        {
+          "id": "lesson-promotion",
+          "criteria": [
+            { "name": "grounding", "weight": 0.45, "min_pass": 0.7 },
+            { "name": "scope_accuracy", "weight": 0.35, "min_pass": 0.7 },
+            { "name": "generality", "weight": 0.2, "min_pass": 0.6 }
+          ],
+          "score_threshold": 0.75,
+          "judge_types": ["standard", "adversarial"],
+          "gate_policy": "majority"
+        },
+        {
+          "id": "lesson-promotion-public",
+          "criteria": [
+            { "name": "grounding", "weight": 0.32, "min_pass": 0.7 },
+            { "name": "scope_accuracy", "weight": 0.24, "min_pass": 0.7 },
+            { "name": "generality", "weight": 0.14, "min_pass": 0.6 },
+            { "name": "disclosure", "weight": 0.3, "min_pass": 0.9 }
+          ],
+          "score_threshold": 0.75,
+          "judge_types": ["standard", "adversarial"],
+          "gate_policy": "majority"
+        }
+      ]
     },
     "durability_filter": {
       "marker_phrases": [

package/plugins/librarian/docs/adr/002-agent-definitions-are-shared-assets.md

@@ -0,0 +1,82 @@
+# ADR-002: Agent definitions are shared assets; hooks are not
+
+## Status
+
+Accepted.
+
+## Context
+
+CLAUDE.md states: "Plugins communicate by emitting events to the JSONL log —
+they do not call each other directly. All plugins depend on the ecosystem
+substrate; no plugin depends on another plugin directly."
+
+Lesson judging (`ecosystem-4z8.3`) needs a jury. Tribunal ships three judge
+agent definitions and the rubric vocabulary. The stage couples librarian and
+tribunal in some direction no matter how it is arranged: either librarian
+reaches for tribunal's judges, or tribunal reaches into librarian's
+project-keyed proposal files and writes verdicts back into them.
+
+## Decision
+
+The invariant forbids **runtime** coupling — one plugin's hook or library
+calling another's, which makes one plugin's failure another's. It does not
+forbid reusing a **published agent definition** by name.
+
+Librarian therefore owns the `judge` verb, both rubrics, the aggregate, and the
+gate decision, and dispatches `tribunal-judge-standard` and
+`tribunal-judge-adversarial` by name.
+
+Librarian does **not** source any file under `plugins/tribunal/`. It implements
+its own aggregate and gate — roughly twenty lines — rather than calling
+`tribunal_aggregate` or `tribunal_gate_decide`.
+
+## Rationale
+
+An agent definition is declarative: a markdown file with frontmatter and a
+prompt. It has no runtime surface and cannot fail at call time in a way that
+propagates — the harness resolves it, librarian never invokes tribunal's code
+directly. That is a real difference from sourcing tribunal's bash, where a
+signature change to `tribunal_gate_decide` breaks librarian mid-call and
+neither plugin's tests would catch it.
+
+It is a weaker guarantee than depending on a published schema, though.
+`@onlooker-community/schema` is registered and drift-checked in CI (see
+[ADR-005](../../../../docs/adr/005-runtime-emitter-fails-open.md)): a breaking
+change to it fails a build before it ships. A judge agent's prompt carries no
+such contract — nothing in either plugin's test suite stops a maintainer from
+narrowing or repurposing what `tribunal-judge-standard` returns without
+touching the agent's name. Calling that "closer to a published schema than to
+calling another plugin's code" overstated the guarantee; only the *loud*
+failure modes — the judge being renamed or removed — actually behave like a
+schema break. See Consequences for what happens when the drift is quiet
+instead.
+
+Keeping the lifecycle in librarian also keeps `ecosystem-4z8.4`'s pool and
+ledger in one plugin instead of splitting them across two.
+
+## Consequences
+
+A judge agent renamed or removed in tribunal breaks lesson judging at dispatch
+time. That is a visible, loud failure at the moment a human invokes the verb —
+not a silent one — and the "could not judge" path already handles it: the
+candidate stays `confirmed` and nothing is written.
+
+A judge agent silently edited in place is a different, unmitigated risk. If a
+maintainer changes what a judge returns without renaming it — dropping
+`judge_type`, redefining what `feedback_summary` means, rescaling `score` —
+nothing in this pipeline notices at edit time, because the agent definition
+carries no drift check the way `@onlooker-community/schema` does. The
+`usable` panel check in `librarian-lesson-judge.sh` only catches the subset of
+that risk that changes the verdict's *shape*: it requires `judge_type` to be a
+string, `score` a number, and `passed` a boolean, and returns UNJUDGED rather
+than a false rejection if any is missing or mistyped. A *semantic* change —
+same shape, different meaning, such as a score scale moving from 0–1 to
+0–100 — passes that check and is judged normally, with no signal to librarian
+or its maintainers that the verdict no longer means what the aggregate and
+gate assume it means. This ADR accepts that risk rather than closing it;
+closing it would require either a real schema contract for judge output or
+librarian validating semantics it does not own.
+
+Librarian's gate logic can drift from tribunal's. Accepted deliberately: they
+answer different questions. Tribunal gates an Actor's output with retry;
+librarian gates a fixed artifact with none.

package/plugins/librarian/scripts/hooks/librarian-session-end.sh

@@ -435,11 +435,32 @@ done
 #
 # Runs over the same durability survivors the classifier saw. Each artifact is
 # independent: a decline or an outage on one never stops the rest.
+#
+# Budgeted in aggregate, not just per call. Each transform carries a 20s
+# ceiling of its own, but nothing bounded KEPT_COUNT of them end to end, so a
+# backlog could hold SessionEnd open for minutes (ecosystem-qwi). The check is
+# per iteration rather than once before the loop: a pre-loop gate only decides
+# whether to start, and once started the cost is still unbounded — which is the
+# gap the classifier loop above still has.
+#
+# Skipping is the safe direction. Untransformed artifacts are reconsidered on a
+# later session, so the cost of stopping early is a delay; the cost of not
+# stopping is a session that will not close.
 # ---------------------------------------------------------------------------
 LESSON_PROPOSED=0
 LESSON_DECLINED=0
+LESSONS_SKIPPED=0
+
+LESSON_BUDGET_MS=$(librarian_config_get '.librarian.lesson_transform.total_budget_ms' 2>/dev/null)
+[[ -z "$LESSON_BUDGET_MS" || "$LESSON_BUDGET_MS" == "null" ]] && LESSON_BUDGET_MS=8000
+LESSON_START_MS=$(librarian_now_ms)
 
 for ((li = 0; li < KEPT_COUNT; li++)); do
+	if [[ $(( $(librarian_now_ms) - LESSON_START_MS )) -ge "$LESSON_BUDGET_MS" ]]; then
+		LESSONS_SKIPPED=$(( KEPT_COUNT - li ))
+		break
+	fi
+
 	LESSON_ARTIFACT=$(printf '%s' "$KEPT" | jq -c ".[$li]")
 	[[ -z "$LESSON_ARTIFACT" || "$LESSON_ARTIFACT" == "null" ]] && continue
 
@@ -450,6 +471,11 @@ for ((li = 0; li < KEPT_COUNT; li++)); do
 	esac
 done
 
+# LESSONS_SKIPPED rides on scan.complete below rather than becoming an event of
+# its own. A truncated stage 5 is not a truncated scan: the scan finishes
+# normally and only this stage stops early, so the count belongs beside a
+# healthy outcome rather than replacing it.
+
 # ----------------------------------------------------------------------------
 # Watermark advance + scan.complete.
 # ----------------------------------------------------------------------------
@@ -465,12 +491,14 @@ librarian_emit "librarian.scan.complete" "$SESSION_ID" "$(jq -cn \
 	--arg outcome "$OUTCOME" \
 	--argjson candidates_proposed "$PROPOSED_COUNT" \
 	--argjson candidates_dropped "$TOTAL_DROPPED" \
+	--argjson lessons_skipped "$LESSONS_SKIPPED" \
 	--argjson duration_ms "$DURATION_MS" \
 	--argjson artifact_count_in_window "$ARTIFACT_COUNT" \
 	'{
 		outcome: $outcome,
 		candidates_proposed: $candidates_proposed,
 		candidates_dropped: $candidates_dropped,
+		lessons_skipped: $lessons_skipped,
 		duration_ms: $duration_ms,
 		artifact_count_in_window: $artifact_count_in_window
 	}')"