@onlooker-community/ecosystem 0.19.0 → 0.20.0

package/plugins/librarian/scripts/lib/librarian-storage.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# Storage layout helpers for Librarian.
+#
+# Layout (under $ONLOOKER_DIR/librarian/<project-key>/):
+#   manifest.json              project metadata: remote_url, repo_root, last_scan_at
+#   last_scan.json             { "scanned_at": ISO-8601 } — watermark for incremental scans
+#   proposals/<ulid>.json      one pending/resolved proposal per file
+#   tombstones/<body_hash>.json one tombstone per rejected/pruned body
+#
+# All paths inside proposals are stored relative to the repo root where they
+# originated. The typed memory store the user maintains lives elsewhere
+# (~/.claude/projects/<encoded>/memory/) and is resolved at promotion time.
+
+# ============================================================================
+# Path helpers
+# ============================================================================
+
+librarian_storage_root() {
+	local base="${ONLOOKER_DIR:-$HOME/.onlooker}"
+	printf '%s/librarian' "$base"
+}
+
+librarian_project_dir() {
+	local key="$1"
+	printf '%s/%s' "$(librarian_storage_root)" "$key"
+}
+
+librarian_proposals_dir() {
+	local key="$1"
+	printf '%s/proposals' "$(librarian_project_dir "$key")"
+}
+
+librarian_tombstones_dir() {
+	local key="$1"
+	printf '%s/tombstones' "$(librarian_project_dir "$key")"
+}
+
+librarian_storage_init() {
+	local key="$1"
+	[[ -z "$key" ]] && return 1
+	local project_dir
+	project_dir=$(librarian_project_dir "$key")
+	mkdir -p \
+		"$project_dir/proposals" \
+		"$project_dir/tombstones" 2>/dev/null
+}
+
+# ============================================================================
+# Manifest
+# ============================================================================
+
+# Usage: librarian_storage_write_manifest <key> <remote_url> <repo_root>
+librarian_storage_write_manifest() {
+	local key="$1"
+	local remote_url="$2"
+	local repo_root="$3"
+	[[ -z "$key" ]] && return 1
+
+	librarian_storage_init "$key" || return 1
+
+	local manifest_path
+	manifest_path="$(librarian_project_dir "$key")/manifest.json"
+	local now
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+	jq -n \
+		--arg key "$key" \
+		--arg remote "$remote_url" \
+		--arg root "$repo_root" \
+		--arg now "$now" \
+		'{
+			project_key: $key,
+			remote_url: (if $remote == "" then null else $remote end),
+			repo_root: (if $root == "" then null else $root end),
+			last_seen_at: $now
+		}' > "$manifest_path" 2>/dev/null
+}
+
+# ============================================================================
+# Scan watermark
+# ============================================================================
+
+librarian_last_scan_path() {
+	local key="$1"
+	printf '%s/last_scan.json' "$(librarian_project_dir "$key")"
+}
+
+# Read the last scan time as ISO-8601, or empty if never scanned.
+librarian_storage_read_last_scan() {
+	local key="$1"
+	local path
+	path=$(librarian_last_scan_path "$key")
+	[[ -f "$path" ]] || return 0
+	jq -r '.scanned_at // empty' "$path" 2>/dev/null
+}
+
+# Write the current time as the new watermark.
+librarian_storage_write_last_scan() {
+	local key="$1"
+	[[ -z "$key" ]] && return 1
+	librarian_storage_init "$key" || return 1
+	local now path
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+	path=$(librarian_last_scan_path "$key")
+	jq -n --arg t "$now" '{ scanned_at: $t }' > "$path" 2>/dev/null
+}
+
+# ============================================================================
+# Proposal storage
+# ============================================================================
+
+# Write a single proposal file. Usage:
+#   librarian_storage_write_proposal <key> <ulid> <json>
+librarian_storage_write_proposal() {
+	local key="$1"
+	local id="$2"
+	local json="$3"
+	[[ -z "$key" || -z "$id" || -z "$json" ]] && return 1
+
+	librarian_storage_init "$key" || return 1
+	local out_path
+	out_path="$(librarian_proposals_dir "$key")/${id}.json"
+	printf '%s\n' "$json" > "$out_path" 2>/dev/null && printf '%s' "$out_path"
+}
+
+# Read all proposals for a project key as a JSON array. Each entry is the raw
+# proposal JSON. Order is unspecified; callers sort/filter as needed.
+librarian_storage_load_proposals() {
+	local key="$1"
+	[[ -z "$key" ]] && { echo '[]'; return 0; }
+
+	local dir
+	dir=$(librarian_proposals_dir "$key")
+	[[ -d "$dir" ]] || { echo '[]'; return 0; }
+
+	local file all='[]'
+	for file in "$dir"/*.json; do
+		[[ -f "$file" ]] || continue
+		local item
+		item=$(jq '.' "$file" 2>/dev/null) || continue
+		all=$(printf '%s' "$all" | jq --argjson item "$item" '. + [$item]')
+	done
+	printf '%s' "$all"
+}
+
+# Count pending proposals (status == "pending").
+librarian_storage_count_pending() {
+	local key="$1"
+	local all
+	all=$(librarian_storage_load_proposals "$key")
+	printf '%s' "$all" | jq '[.[] | select((.status // "pending") == "pending")] | length' 2>/dev/null
+}
+
+# ============================================================================
+# Tombstone storage
+# ============================================================================
+
+# Write a tombstone keyed by body hash. Usage:
+#   librarian_storage_write_tombstone <key> <body_hash> <original_filename>
+librarian_storage_write_tombstone() {
+	local key="$1"
+	local body_hash="$2"
+	local original_filename="${3:-}"
+	[[ -z "$key" || -z "$body_hash" ]] && return 1
+
+	librarian_storage_init "$key" || return 1
+	local out_path now
+	out_path="$(librarian_tombstones_dir "$key")/${body_hash}.json"
+	now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+	jq -n \
+		--arg body_hash "$body_hash" \
+		--arg original "$original_filename" \
+		--arg created "$now" \
+		'{
+			body_hash: $body_hash,
+			original_filename: (if $original == "" then null else $original end),
+			created_at: $created
+		}' > "$out_path" 2>/dev/null
+}
+
+# Returns 0 if a tombstone exists for this body hash (and is not expired).
+# Usage: librarian_storage_has_tombstone <key> <body_hash> <ttl_days>
+librarian_storage_has_tombstone() {
+	local key="$1"
+	local body_hash="$2"
+	local ttl_days="${3:-180}"
+	[[ -z "$key" || -z "$body_hash" ]] && return 1
+
+	local path
+	path="$(librarian_tombstones_dir "$key")/${body_hash}.json"
+	[[ -f "$path" ]] || return 1
+
+	local created_at age_days
+	created_at=$(jq -r '.created_at // empty' "$path" 2>/dev/null)
+	[[ -z "$created_at" ]] && return 0
+
+	# Age check via python3 for portable date math.
+	age_days=$(python3 -c "
+import sys, datetime
+created = datetime.datetime.strptime(sys.argv[1], '%Y-%m-%dT%H:%M:%SZ').replace(tzinfo=datetime.timezone.utc)
+now = datetime.datetime.now(datetime.timezone.utc)
+print(int((now - created).days))
+" "$created_at" 2>/dev/null) || age_days=0
+
+	(( age_days <= ttl_days ))
+}
+
+# Compute a stable hash of a normalized memory body. Used for tombstone keys
+# and conflict-state dedup. Strips whitespace runs and lowercases.
+librarian_body_hash() {
+	local body="$1"
+	local normalized
+	normalized=$(printf '%s' "$body" | tr '[:upper:]' '[:lower:]' | tr -s '[:space:]' ' ' | sed 's/^ //;s/ $//')
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$normalized" | shasum -a 256 2>/dev/null | cut -c1-16
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$normalized" | sha256sum 2>/dev/null | cut -c1-16
+	else
+		return 1
+	fi
+}

package/plugins/librarian/scripts/lib/librarian-ulid.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for Librarian proposal and tombstone IDs.
+#
+# Spec: https://github.com/ulid/spec
+#   - 48-bit timestamp (ms since epoch) → 10 chars Crockford Base32
+#   - 80-bit randomness → 16 chars Crockford Base32
+#   - lexicographically sortable, time-ordered
+#
+# Monotonicity across rapid bursts inside a single ms is not required; librarian
+# writes proposals at SessionEnd and SessionStart cadence, never in tight loops.
+
+_LIBRARIAN_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+# Encode a decimal integer to a fixed-length Crockford Base32 string (uppercase).
+# Usage: _librarian_ulid_encode <integer> <length>
+_librarian_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_LIBRARIAN_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+# Generate one ULID. Prints 26 chars (timestamp + randomness).
+librarian_ulid() {
+	local now_ms
+	if [[ "$(uname)" == "Darwin" ]]; then
+		now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+			|| now_ms=$(($(date +%s) * 1000))
+	else
+		now_ms=$(date +%s%3N 2>/dev/null) || now_ms=$(($(date +%s) * 1000))
+	fi
+
+	local rand_hi rand_lo
+	rand_hi=$((RANDOM * 32768 + RANDOM))
+	rand_lo=$((RANDOM * 32768 + RANDOM))
+	rand_hi=$(((rand_hi * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+	rand_lo=$(((rand_lo * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+
+	local ts_part hi_part lo_part
+	ts_part=$(_librarian_ulid_encode "$now_ms" 10)
+	hi_part=$(_librarian_ulid_encode "$rand_hi" 8)
+	lo_part=$(_librarian_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/release-please-config.json

@@ -158,6 +158,22 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/librarian": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "librarian",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"

package/test/bats/librarian-session-end.bats

@@ -0,0 +1,182 @@
+#!/usr/bin/env bats
+#
+# Exercises the librarian SessionEnd scan pipeline end-to-end with a stub
+# `claude` CLI. Verifies:
+#   - Disabled config: no proposals, no events.
+#   - Empty archivist dir: scan.started + scan.complete{outcome: empty}
+#     emitted, watermark advances.
+#   - Synthetic artifacts that pass durability filter and classifier:
+#     proposals land on disk with the expected provenance and scan events
+#     report the correct counts.
+#   - Durability-filtered artifacts (no marker phrase) emit
+#     candidate.dropped events.
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/librarian"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+
+  # Stand up a fake project repo so project-key resolution succeeds.
+  PROJECT_REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$PROJECT_REPO"
+  git -C "$PROJECT_REPO" init -q
+  git -C "$PROJECT_REPO" config user.email t@example.com
+  git -C "$PROJECT_REPO" config user.name "Test"
+  git -C "$PROJECT_REPO" remote add origin git@github.com:org/librarian-scan-test.git
+
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+  PROJECT_KEY=$(librarian_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+
+  ARCHIVIST_DIR="${ONLOOKER_DIR}/archivist/${PROJECT_KEY}"
+  LIBRARIAN_DIR="${ONLOOKER_DIR}/librarian/${PROJECT_KEY}"
+  ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+
+  # Project-scoped settings.json that enables librarian.
+  mkdir -p "${PROJECT_REPO}/.claude"
+  printf '%s\n' '{"librarian":{"enabled":true}}' > "${PROJECT_REPO}/.claude/settings.json"
+
+  # Stub `claude` CLI on PATH. Returns a deterministic classifier response
+  # based on the artifact's summary contents.
+  STUB_BIN="${BATS_TEST_TMPDIR}/bin"
+  mkdir -p "$STUB_BIN"
+  cat > "${STUB_BIN}/claude" <<'STUB'
+#!/usr/bin/env bash
+# Read the prompt from stdin and decide which classifier response to emit.
+prompt=$(cat)
+if [[ "$prompt" == *"prefer-functional-stub"* ]]; then
+  printf '%s' '{"type":"feedback","title":"Prefer functional patterns","body":"User prefers functional patterns over class-based.\n\n**Why:** Stated explicitly during code review.\n**How to apply:** Default to plain functions and composition.","confidence":0.84}'
+elif [[ "$prompt" == *"compliance-stub"* ]]; then
+  printf '%s' '{"type":"project","title":"Auth rewrite is compliance driven","body":"Auth middleware rewrite is driven by legal/compliance requirements around session token storage.\n\n**Why:** Compliance ask, not tech debt cleanup.\n**How to apply:** Favor compliance posture over ergonomics when scoping.","confidence":0.91}'
+elif [[ "$prompt" == *"low-conf-stub"* ]]; then
+  printf '%s' '{"type":"user","title":"User edits","body":"User edits files.","confidence":0.4}'
+else
+  printf '%s' '{"type":null,"title":"","body":"","confidence":0.2}'
+fi
+STUB
+  chmod +x "${STUB_BIN}/claude"
+  export PATH="${STUB_BIN}:${PATH}"
+
+  HOOK="${PLUGIN_ROOT}/scripts/hooks/librarian-session-end.sh"
+}
+
+# Helper: write an archivist artifact for the project.
+_seed_artifact() {
+  local kind="$1" id="$2" summary="$3" detail="$4" created_at="${5:-2026-06-01T12:00:00Z}"
+  local dir="${ARCHIVIST_DIR}/${kind}"
+  mkdir -p "$dir"
+  jq -n \
+    --arg id "$id" --arg kind "${kind%s}" \
+    --arg project_key "$PROJECT_KEY" \
+    --arg summary "$summary" --arg detail "$detail" \
+    --arg created_at "$created_at" --arg session_id "sess-1" \
+    '{ id: $id, kind: $kind, project_key: $project_key, source: "local",
+       created_at: $created_at, updated_at: $created_at,
+       summary: $summary, detail: $detail, files: [], session_id: $session_id }' \
+    > "${dir}/${id}.json"
+}
+
+_hook_input() {
+  jq -cn --arg cwd "$PROJECT_REPO" --arg sid "sess-end-test" \
+    '{cwd: $cwd, session_id: $sid, hook_event_name: "SessionEnd"}'
+}
+
+@test "session-end is a no-op when librarian is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  # No proposals written.
+  [ ! -d "${LIBRARIAN_DIR}/proposals" ] || [ -z "$(ls -A "${LIBRARIAN_DIR}/proposals" 2>/dev/null)" ]
+  # No events emitted.
+  [ ! -f "$ONLOOKER_EVENTS_LOG" ] || ! grep -q 'librarian' "$ONLOOKER_EVENTS_LOG"
+}
+
+@test "session-end emits empty scan when archivist has nothing" {
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # scan.started fired with artifact_count_in_window = 0.
+  grep -q '"event_type":"librarian.scan.started"' "$ONLOOKER_EVENTS_LOG"
+  grep '"event_type":"librarian.scan.started"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.artifact_count_in_window == 0' >/dev/null
+
+  # scan.complete fired with outcome=empty and zero counts.
+  grep -q '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG"
+  grep '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty" and .payload.candidates_proposed == 0 and .payload.candidates_dropped == 0' >/dev/null
+
+  # Watermark advanced for next scan.
+  [ -f "${LIBRARIAN_DIR}/last_scan.json" ]
+  jq -e '.scanned_at | test("^[0-9]{4}-[0-9]{2}-[0-9]{2}T")' "${LIBRARIAN_DIR}/last_scan.json" >/dev/null
+}
+
+@test "session-end proposes promotion for marker-phrase + classifier success" {
+  # Seed two promotable artifacts and one filter-rejected one.
+  _seed_artifact "decisions" "01PROPOSEEFEEDBACK00000000" \
+    "User prefers functional patterns prefer-functional-stub" \
+    "User explicitly said: always prefer plain functions over classes when adding new code in the api layer."
+
+  _seed_artifact "decisions" "01PROPOSEEPROJECT000000000" \
+    "Compliance-driven auth rewrite compliance-stub" \
+    "The reason for the auth middleware rewrite is legal compliance, not tech debt; remember this when sizing scope."
+
+  _seed_artifact "open_questions" "01FILTERREJECTED000000000" \
+    "ad hoc question" \
+    "this short text contains no marker phrase and should be filtered out before the classifier runs"
+
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # Two proposals on disk.
+  proposals=("${LIBRARIAN_DIR}/proposals"/*.json)
+  [ "${#proposals[@]}" -eq 2 ]
+
+  # Both carry provenance back to their source artifact.
+  for p in "${proposals[@]}"; do
+    jq -e '.status == "pending" and .conflict_state == "none"' "$p" >/dev/null
+    jq -e '.proposed.type | IN("user", "feedback", "project", "reference")' "$p" >/dev/null
+    jq -e '.proposed.classifier_confidence >= 0.6' "$p" >/dev/null
+    jq -e '(.source_artifact_ids | length) > 0' "$p" >/dev/null
+  done
+
+  # scan.started reported the right window size (2 marker matches + 1 filtered = 3).
+  grep '"event_type":"librarian.scan.started"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.artifact_count_in_window == 3' >/dev/null
+
+  # candidate.proposed fired twice with correct types.
+  proposed_types=$(grep '"event_type":"librarian.candidate.proposed"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -r '.payload.memory_type' | sort | paste -sd, -)
+  [ "$proposed_types" = "feedback,project" ]
+
+  # candidate.dropped fired for the marker-missing artifact.
+  grep '"event_type":"librarian.candidate.dropped"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.reason == "filter_marker_missing")' >/dev/null
+
+  # scan.complete with ok outcome and accurate counts.
+  scan_complete=$(grep '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG")
+  echo "$scan_complete" | jq -e '.payload.outcome == "ok" and .payload.candidates_proposed == 2 and .payload.candidates_dropped >= 1' >/dev/null
+}
+
+@test "session-end drops candidates below confidence floor" {
+  _seed_artifact "decisions" "01LOWCONFCANDIDATE0000000" \
+    "low-conf-stub trigger" \
+    "always prefer some thing because reasons that show a marker phrase but the stub returns low confidence"
+
+  run bash -c "printf '%s' '$(_hook_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+
+  # No proposal written.
+  [ ! -d "${LIBRARIAN_DIR}/proposals" ] || [ -z "$(ls -A "${LIBRARIAN_DIR}/proposals" 2>/dev/null)" ]
+
+  # candidate.dropped fired with low_confidence reason.
+  grep '"event_type":"librarian.candidate.dropped"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e 'select(.payload.reason == "low_confidence")' >/dev/null
+
+  # scan.complete reports empty outcome (zero proposals).
+  grep '"event_type":"librarian.scan.complete"' "$ONLOOKER_EVENTS_LOG" \
+    | jq -e '.payload.outcome == "empty" and .payload.candidates_proposed == 0 and .payload.candidates_dropped >= 1' >/dev/null
+}

package/test/bats/librarian-session-start.bats

@@ -0,0 +1,136 @@
+#!/usr/bin/env bats
+#
+# Tests the librarian SessionStart surfacer. Verifies:
+#   - Disabled config: empty additionalContext, exit 0.
+#   - No git context: empty additionalContext, exit 0.
+#   - Empty proposal queue + skip_inject_when_zero=true: empty context.
+#   - Pending proposals: one-line pointer with the count and pluralization.
+#   - Overflow: counts above max_pending_for_inject render as "<cap>+".
+
+setup() {
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/librarian"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  export ONLOOKER_ECOSYSTEM_ROOT="$REPO_ROOT"
+
+  PROJECT_REPO="${BATS_TEST_TMPDIR}/repo"
+  mkdir -p "$PROJECT_REPO"
+  git -C "$PROJECT_REPO" init -q
+  git -C "$PROJECT_REPO" config user.email t@example.com
+  git -C "$PROJECT_REPO" config user.name "Test"
+  git -C "$PROJECT_REPO" remote add origin git@github.com:org/librarian-surfacer-test.git
+
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+  PROJECT_KEY=$(librarian_project_key "$PROJECT_REPO")
+  [ -n "$PROJECT_KEY" ]
+  LIBRARIAN_DIR="${ONLOOKER_DIR}/librarian/${PROJECT_KEY}"
+
+  mkdir -p "${PROJECT_REPO}/.claude"
+  printf '%s\n' '{"librarian":{"enabled":true}}' > "${PROJECT_REPO}/.claude/settings.json"
+
+  HOOK="${PLUGIN_ROOT}/scripts/hooks/librarian-session-start.sh"
+}
+
+_input() {
+  jq -cn --arg cwd "$PROJECT_REPO" \
+    '{cwd: $cwd, source: "startup", session_id: "sess-start-test"}'
+}
+
+# Helper: drop a proposal file with the given status into the queue.
+_seed_proposal() {
+  local id="$1" status="${2:-pending}"
+  mkdir -p "${LIBRARIAN_DIR}/proposals"
+  jq -n --arg id "$id" --arg status "$status" \
+    '{
+      id: $id,
+      created_at: "2026-06-01T00:00:00Z",
+      source_artifact_ids: [],
+      source_session_ids: [],
+      proposed: { type: "feedback", filename: ($id + ".md"),
+                  title: "t", body: "b", classifier_confidence: 0.8 },
+      conflict_state: "none",
+      conflict_with: [],
+      status: $status
+    }' > "${LIBRARIAN_DIR}/proposals/${id}.json"
+}
+
+@test "surfacer emits empty context when librarian is disabled" {
+  rm -f "${PROJECT_REPO}/.claude/settings.json"
+  _seed_proposal "01PROPOSALA000000000000000"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+  echo "$output" | jq -e '.hookSpecificOutput.hookEventName == "SessionStart"' >/dev/null
+}
+
+@test "surfacer emits empty context when there is no git context" {
+  local non_git="${BATS_TEST_TMPDIR}/no-git"
+  mkdir -p "$non_git"
+  local input
+  input=$(jq -cn --arg cwd "$non_git" '{cwd: $cwd, source: "startup", session_id: "s"}')
+
+  run bash -c "printf '%s' '$input' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+}
+
+@test "surfacer emits empty context when no proposals are pending" {
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  echo "$output" | jq -e '.hookSpecificOutput.additionalContext == ""' >/dev/null
+}
+
+@test "surfacer surfaces one-line pointer when proposals exist (plural)" {
+  _seed_proposal "01PROPOSAL11111111111111A"
+  _seed_proposal "01PROPOSAL11111111111111B"
+  _seed_proposal "01PROPOSAL11111111111111C"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Librarian has 3 pending memory promotion proposals"* ]]
+  [[ "$ctx" == *"/librarian review"* ]]
+}
+
+@test "surfacer pluralizes singular vs plural correctly" {
+  _seed_proposal "01PROPOSALSINGULAR0000000"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Librarian has 1 pending memory promotion proposal"* ]]
+  [[ "$ctx" != *"proposals."* ]]
+}
+
+@test "surfacer ignores accepted/rejected proposals when counting pending" {
+  _seed_proposal "01PROPOSALACCEPTED000000" "accepted"
+  _seed_proposal "01PROPOSALREJECTED000000" "rejected"
+  _seed_proposal "01PROPOSALPENDING0000000" "pending"
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"1 pending memory promotion proposal"* ]]
+}
+
+@test "surfacer caps display at max_pending_for_inject + '+'" {
+  # Override max to 3 via a project settings overlay.
+  printf '%s\n' '{"librarian":{"enabled":true,"surfacer":{"max_pending_for_inject":3}}}' \
+    > "${PROJECT_REPO}/.claude/settings.json"
+  for i in A B C D E; do
+    _seed_proposal "01PROPOSALCAP$i$i$i$i$i$i$i$i$i$i$i$i"
+  done
+
+  run bash -c "printf '%s' '$(_input)' | '$HOOK'"
+  [ "$status" -eq 0 ]
+  local ctx
+  ctx=$(echo "$output" | jq -r '.hookSpecificOutput.additionalContext')
+  [[ "$ctx" == *"Librarian has 3+ pending memory promotion proposals"* ]]
+}