@onlooker-community/ecosystem 0.27.0 → 0.28.0

package/test/bats/lineage-config.bats

@@ -0,0 +1,73 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/lineage"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-config.sh"
+}
+
+@test "lineage is disabled by default" {
+	lineage_config_load ""
+	run lineage_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "user-level settings.json can enable lineage" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"lineage":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	lineage_config_load ""
+	run lineage_config_enabled
+	[ "$status" -eq 0 ]
+}
+
+@test "repo-level settings.json overrides user-level" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"lineage":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+	local repo="${BATS_TEST_TMPDIR}/repo"
+	mkdir -p "${repo}/.claude"
+	printf '%s\n' '{"lineage":{"enabled":false}}' > "${repo}/.claude/settings.json"
+	lineage_config_load "$repo"
+	run lineage_config_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "default max_snippet_chars is 4000" {
+	lineage_config_load ""
+	[ "$(lineage_config_max_snippet_chars)" = "4000" ]
+}
+
+@test "max_snippet_chars is configurable" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"lineage":{"max_snippet_chars":256}}' > "${HOME}/.claude/settings.json"
+	lineage_config_load ""
+	[ "$(lineage_config_max_snippet_chars)" = "256" ]
+}
+
+@test "redaction is on by default and can be disabled with an explicit false" {
+	lineage_config_load ""
+	run lineage_config_redact_enabled
+	[ "$status" -eq 0 ]
+
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"lineage":{"redact_secrets":false}}' > "${HOME}/.claude/settings.json"
+	lineage_config_load ""
+	run lineage_config_redact_enabled
+	[ "$status" -ne 0 ]
+}
+
+@test "default prompt_source is historian_then_transcript" {
+	lineage_config_load ""
+	[ "$(lineage_config_prompt_source)" = "historian_then_transcript" ]
+}
+
+@test "ignore_globs are exposed one per line" {
+	lineage_config_load ""
+	run lineage_config_ignore_globs
+	[ "$status" -eq 0 ]
+	[[ "$output" == *"node_modules"* ]]
+	[[ "$output" == *".lock"* ]]
+}

package/test/bats/lineage-events.bats

@@ -0,0 +1,81 @@
+#!/usr/bin/env bats
+
+# Validates that lineage.* events pass @onlooker-community/schema validation.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/lineage"
+	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"
+
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-events.sh"
+
+	export CLAUDE_SESSION_ID="bats-lineage-session-$$"
+	PK="proj0123abcd"
+	SID="bats-lineage-sid-000"
+}
+
+_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
+}
+
+@test "lineage.change.recorded validates (full payload)" {
+	local p
+	p=$(jq -n --arg pk "$PK" --arg sid "$SID" \
+		'{project_key:$pk, session_id:$sid, file_path:"src/main.ts", tool:"Edit",
+		  operation:"edit", change_id:"01JLNG0000000000000000CHG1", turn:4,
+		  tool_use_id:"toolu_1", lines_added:3, lines_removed:1, bytes:142,
+		  edit_count:1, content_sha256:"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}')
+	lineage_emit_event "lineage.change.recorded" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "lineage.change.recorded validates (minimal Write)" {
+	local p
+	p=$(jq -n --arg pk "$PK" --arg sid "$SID" \
+		'{project_key:$pk, session_id:$sid, file_path:"README.md", tool:"Write", operation:"create"}')
+	lineage_emit_event "lineage.change.recorded" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "lineage.query.answered validates" {
+	local p
+	p=$(jq -n --arg pk "$PK" \
+		'{project_key:$pk, file_path:"src/main.ts", matches:2, query:"src/main.ts:42", line:42, resolved_via:"historian"}')
+	lineage_emit_event "lineage.query.answered" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "lineage.query.answered validates with no matches" {
+	local p
+	p=$(jq -n --arg pk "$PK" \
+		'{project_key:$pk, file_path:"src/gone.ts", matches:0, resolved_via:"none"}')
+	lineage_emit_event "lineage.query.answered" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "an invalid tool enum is rejected by the schema" {
+	local p
+	p=$(jq -n --arg pk "$PK" --arg sid "$SID" \
+		'{project_key:$pk, session_id:$sid, file_path:"x", tool:"NotebookEdit", operation:"edit"}')
+	run lineage_emit_event "lineage.change.recorded" "$p" "$SID"
+	[ "$status" -ne 0 ]
+}
+
+@test "lineage_emit_event returns nonzero for an unknown event type" {
+	run lineage_emit_event "lineage.no_such_event" '{"project_key":"x"}' "$SID"
+	[ "$status" -ne 0 ]
+}

package/test/bats/lineage-post-tool-use.bats

@@ -0,0 +1,115 @@
+#!/usr/bin/env bats
+
+# Exercises the PostToolUse hook end-to-end against an isolated $ONLOOKER_DIR.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/lineage"
+	HOOK="${PLUGIN_ROOT}/scripts/hooks/lineage-post-tool-use.sh"
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")" "${ONLOOKER_DIR}/session-trackers"
+
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-project-key.sh"
+
+	REPO="${BATS_TEST_TMPDIR}/proj"
+	mkdir -p "$REPO"
+	git init -q "$REPO" 2>/dev/null
+	git -C "$REPO" remote add origin https://example.com/onlooker/lineage-test.git 2>/dev/null
+	KEY=$(lineage_project_key "$REPO")
+	SID="bats-lin-001"
+}
+
+_enable() {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"lineage":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+}
+
+_ledger() { printf '%s/lineage/%s/changes.jsonl' "$ONLOOKER_DIR" "$KEY"; }
+
+# _run <tool> <file_path> <tool_input_json>
+_run() {
+	local tool="$1" file="$2" ti="$3"
+	jq -nc --arg sid "$SID" --arg cwd "$REPO" --arg tool "$tool" --argjson ti "$ti" \
+		'{session_id:$sid, cwd:$cwd, tool_name:$tool, tool_use_id:"toolu_x", transcript_path:"", tool_input:$ti}' \
+		> "${BATS_TEST_TMPDIR}/in.json"
+	run bash "$HOOK" < "${BATS_TEST_TMPDIR}/in.json"
+}
+
+@test "records an Edit change into the project ledger" {
+	_enable
+	_run Edit "${REPO}/foo.py" "$(jq -nc --arg f "${REPO}/foo.py" '{file_path:$f, old_string:"x = 1", new_string:"x = 2"}')"
+	[ "$status" -eq 0 ]
+	[ -f "$(_ledger)" ]
+	[ "$(jq -rs '.[0].file_path' "$(_ledger)")" = "${REPO}/foo.py" ]
+	[ "$(jq -rs '.[0].tool' "$(_ledger)")" = "Edit" ]
+}
+
+@test "records a single-file MultiEdit (top-level file_path)" {
+	_enable
+	_run MultiEdit "${REPO}/foo.py" "$(jq -nc --arg f "${REPO}/foo.py" \
+		'{file_path:$f, edits:[{old_string:"a", new_string:"a1"},{old_string:"b", new_string:"b1"}]}')"
+	[ "$status" -eq 0 ]
+	[ -f "$(_ledger)" ]
+	[ "$(jq -rs '.[0].file_path' "$(_ledger)")" = "${REPO}/foo.py" ]
+	[ "$(jq -rs '.[0].tool' "$(_ledger)")" = "MultiEdit" ]
+	[ "$(jq -rs '.[0].operation' "$(_ledger)")" = "multi_edit" ]
+}
+
+@test "skips a MultiEdit whose edits span multiple distinct files" {
+	_enable
+	# Hypothetical per-edit-file_path shape spanning two files — skip to avoid misattribution.
+	local ti
+	ti=$(jq -nc --arg a "${REPO}/a.py" --arg b "${REPO}/b.py" \
+		'{edits:[{file_path:$a, old_string:"x", new_string:"x1"},{file_path:$b, old_string:"y", new_string:"y1"}]}')
+	_run MultiEdit "${REPO}/a.py" "$ti"
+	[ "$status" -eq 0 ]
+	[ ! -f "$(_ledger)" ]
+}
+
+@test "records the turn number from the session tracker" {
+	_enable
+	printf '%s' '{"turn_number":7}' > "${ONLOOKER_DIR}/session-trackers/${SID}"
+	_run Write "${REPO}/bar.py" "$(jq -nc --arg f "${REPO}/bar.py" '{file_path:$f, content:"print(1)"}')"
+	[ "$(jq -rs '.[0].turn' "$(_ledger)")" = "7" ]
+}
+
+@test "writes nothing when lineage is disabled" {
+	_run Edit "${REPO}/foo.py" "$(jq -nc --arg f "${REPO}/foo.py" '{file_path:$f, old_string:"a", new_string:"b"}')"
+	[ "$status" -eq 0 ]
+	[ ! -d "${ONLOOKER_DIR}/lineage" ]
+}
+
+@test "skips paths matching ignore_globs" {
+	_enable
+	mkdir -p "${REPO}/node_modules"
+	_run Write "${REPO}/node_modules/x.js" "$(jq -nc --arg f "${REPO}/node_modules/x.js" '{file_path:$f, content:"y"}')"
+	[ "$status" -eq 0 ]
+	[ ! -f "$(_ledger)" ]
+}
+
+@test "skips files outside the repo" {
+	_enable
+	mkdir -p "${BATS_TEST_TMPDIR}/outside"
+	local f="${BATS_TEST_TMPDIR}/outside/x.js"
+	_run Write "$f" "$(jq -nc --arg f "$f" '{file_path:$f, content:"y"}')"
+	[ "$status" -eq 0 ]
+	[ ! -f "$(_ledger)" ]
+}
+
+@test "emits lineage.change.recorded" {
+	_enable
+	_run Edit "${REPO}/foo.py" "$(jq -nc --arg f "${REPO}/foo.py" '{file_path:$f, old_string:"a", new_string:"b"}')"
+	run grep -c '"event_type":"lineage.change.recorded"' "$ONLOOKER_EVENTS_LOG"
+	[ "$output" -ge 1 ]
+}
+
+@test "a distinct subagent session_id is recorded as-is" {
+	_enable
+	SID="bats-subagent-999"
+	_run Edit "${REPO}/foo.py" "$(jq -nc --arg f "${REPO}/foo.py" '{file_path:$f, old_string:"a", new_string:"b"}')"
+	[ "$(jq -rs '.[0].session_id' "$(_ledger)")" = "bats-subagent-999" ]
+}

package/test/bats/lineage-project-key.bats

@@ -0,0 +1,51 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/lineage"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-project-key.sh"
+}
+
+_mk_repo_with_remote() {
+	local dir="$1" url="$2"
+	mkdir -p "$dir"
+	git init -q "$dir" 2>/dev/null
+	git -C "$dir" remote add origin "$url" 2>/dev/null
+}
+
+@test "key is a 12-char hex string for a repo with a remote" {
+	local repo="${BATS_TEST_TMPDIR}/repo-a"
+	_mk_repo_with_remote "$repo" "https://example.com/onlooker/a.git"
+	run lineage_project_key "$repo"
+	[ "$status" -eq 0 ]
+	[ "${#output}" -eq 12 ]
+	[[ "$output" =~ ^[0-9a-f]{12}$ ]]
+}
+
+@test "same cwd yields a stable key" {
+	local repo="${BATS_TEST_TMPDIR}/repo-b"
+	_mk_repo_with_remote "$repo" "https://example.com/onlooker/b.git"
+	local a b
+	a=$(lineage_project_key "$repo")
+	b=$(lineage_project_key "$repo")
+	[ -n "$a" ]
+	[ "$a" = "$b" ]
+}
+
+@test "different remotes yield different keys" {
+	local r1="${BATS_TEST_TMPDIR}/repo-c" r2="${BATS_TEST_TMPDIR}/repo-d"
+	_mk_repo_with_remote "$r1" "https://example.com/onlooker/c.git"
+	_mk_repo_with_remote "$r2" "https://example.com/onlooker/d.git"
+	[ "$(lineage_project_key "$r1")" != "$(lineage_project_key "$r2")" ]
+}
+
+@test "empty key for a non-git directory" {
+	local plain="${BATS_TEST_TMPDIR}/not-a-repo"
+	mkdir -p "$plain"
+	run lineage_project_key "$plain"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}

package/test/bats/lineage-query.bats

@@ -0,0 +1,85 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/lineage"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-redact.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-record.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-query.sh"
+
+	KEY="projqueryabc"
+	FILE="src/a.py"
+	# Two changes to the same file, appended oldest-first.
+	local dir
+	dir=$(lineage_record_dir "$KEY")
+	mkdir -p "$dir"
+	{
+		jq -nc '{change_id:"C1", ts:"2026-06-12T00:00:01Z", ts_epoch:1, session_id:"s1", turn:2, tool:"Edit", operation:"edit", file_path:"src/a.py", added_snippets:["def foo():"], transcript_path:""}'
+		jq -nc '{change_id:"C2", ts:"2026-06-12T00:00:02Z", ts_epoch:2, session_id:"s1", turn:5, tool:"Edit", operation:"edit", file_path:"src/a.py", added_snippets:["    return 42"], transcript_path:""}'
+	} > "${dir}/changes.jsonl"
+}
+
+@test "changes_for_file returns records newest-first" {
+	run lineage_changes_for_file "$KEY" "$FILE"
+	[ "$status" -eq 0 ]
+	local first
+	first=$(printf '%s\n' "$output" | head -1)
+	[ "$(jq -r '.change_id' <<<"$first")" = "C2" ]
+}
+
+@test "match_line content-anchors a line to the change that introduced it" {
+	local rec
+	rec=$(lineage_match_line "$KEY" "$FILE" "return 42")
+	[ "$(jq -r '.change_id' <<<"$rec")" = "C2" ]
+
+	rec=$(lineage_match_line "$KEY" "$FILE" "def foo")
+	[ "$(jq -r '.change_id' <<<"$rec")" = "C1" ]
+}
+
+@test "match_line returns nothing for content no change introduced" {
+	run lineage_match_line "$KEY" "$FILE" "nonexistent content"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "match_line ignores an empty needle" {
+	run lineage_match_line "$KEY" "$FILE" "   "
+	[ -z "$output" ]
+}
+
+@test "resolve_prompt reads historian's chunk for the turn range" {
+	local hist="${ONLOOKER_DIR}/historian/${KEY}/sessions"
+	mkdir -p "$hist"
+	printf '%s\n' '{"session_id":"s1","start_turn_index":1,"end_turn_index":6,"body_redacted":"user: write the foo function\n\nassistant: done"}' \
+		> "${hist}/s1.jsonl"
+	run lineage_resolve_prompt "$KEY" "s1" "5" "" "historian_then_transcript"
+	[ "$status" -eq 0 ]
+	[ "$(jq -r '.resolved_via' <<<"$output")" = "historian" ]
+	[[ "$(jq -r '.prompt' <<<"$output")" == *"write the foo function"* ]]
+}
+
+@test "resolve_prompt falls back to the transcript when historian has nothing" {
+	local tp="${BATS_TEST_TMPDIR}/transcript.jsonl"
+	{
+		printf '%s\n' '{"role":"user","content":"first prompt"}'
+		printf '%s\n' '{"role":"assistant","content":"ok"}'
+		printf '%s\n' '{"role":"user","content":"second prompt about bar"}'
+	} > "$tp"
+	run lineage_resolve_prompt "$KEY" "s2" "2" "$tp" "historian_then_transcript"
+	[ "$status" -eq 0 ]
+	[ "$(jq -r '.resolved_via' <<<"$output")" = "transcript" ]
+	[[ "$(jq -r '.prompt' <<<"$output")" == *"second prompt about bar"* ]]
+}
+
+@test "resolve_prompt reports none when neither source is available" {
+	run lineage_resolve_prompt "$KEY" "s3" "1" "" "historian_then_transcript"
+	[ "$status" -eq 0 ]
+	[ "$(jq -r '.resolved_via' <<<"$output")" = "none" ]
+	[ "$(jq -r '.prompt' <<<"$output")" = "" ]
+}

package/test/bats/lineage-record.bats

@@ -0,0 +1,79 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/lineage"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-redact.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-record.sh"
+	KEY="proj0123abcd"
+}
+
+@test "Edit record captures operation, line counts, snippet, and digest" {
+	local ti rec
+	ti=$(jq -nc '{file_path:"src/a.py", old_string:"a\nb", new_string:"a\nb\nc"}')
+	rec=$(lineage_build_record "CID1" "2026-06-12T00:00:00Z" 1781280000 "sess1" "5" "Edit" "src/a.py" "$ti" 4000 true "")
+	[ "$(jq -r '.tool' <<<"$rec")" = "Edit" ]
+	[ "$(jq -r '.operation' <<<"$rec")" = "edit" ]
+	[ "$(jq -r '.lines_added' <<<"$rec")" = "3" ]
+	[ "$(jq -r '.lines_removed' <<<"$rec")" = "2" ]
+	[ "$(jq -r '.turn' <<<"$rec")" = "5" ]
+	[ "$(jq -r '.added_snippets[0]' <<<"$rec")" = "a
+b
+c" ]
+	[ -n "$(jq -r '.content_sha256' <<<"$rec")" ]
+}
+
+@test "Write record is operation=create with no removed lines" {
+	local ti rec
+	ti=$(jq -nc '{file_path:"README.md", content:"line1\nline2"}')
+	rec=$(lineage_build_record "CID2" "2026-06-12T00:00:00Z" 1781280000 "sess1" "" "Write" "README.md" "$ti" 4000 true "")
+	[ "$(jq -r '.tool' <<<"$rec")" = "Write" ]
+	[ "$(jq -r '.operation' <<<"$rec")" = "create" ]
+	[ "$(jq -r '.lines_added' <<<"$rec")" = "2" ]
+	[ "$(jq -r '.lines_removed' <<<"$rec")" = "0" ]
+}
+
+@test "turn is omitted when empty" {
+	local ti rec
+	ti=$(jq -nc '{file_path:"README.md", content:"x"}')
+	rec=$(lineage_build_record "CID3" "2026-06-12T00:00:00Z" 1781280000 "sess1" "" "Write" "README.md" "$ti" 4000 true "")
+	[ "$(jq -r 'has("turn")' <<<"$rec")" = "false" ]
+}
+
+@test "MultiEdit record reports edit_count and joins added content" {
+	local ti rec
+	ti=$(jq -nc '{file_path:"src/b.py", edits:[{old_string:"x", new_string:"x1"},{old_string:"y", new_string:"y1\ny2"}]}')
+	rec=$(lineage_build_record "CID4" "2026-06-12T00:00:00Z" 1781280000 "sess1" "2" "MultiEdit" "src/b.py" "$ti" 4000 true "")
+	[ "$(jq -r '.tool' <<<"$rec")" = "MultiEdit" ]
+	[ "$(jq -r '.operation' <<<"$rec")" = "multi_edit" ]
+	[ "$(jq -r '.edit_count' <<<"$rec")" = "2" ]
+	[ "$(jq -r '.lines_added' <<<"$rec")" = "3" ]
+	[[ "$(jq -r '.added_snippets[0]' <<<"$rec")" == *"y2"* ]]
+}
+
+@test "append writes one line per record (append-only)" {
+	local ti r1 r2
+	ti=$(jq -nc '{file_path:"src/a.py", content:"a"}')
+	r1=$(lineage_build_record "CID-A" "2026-06-12T00:00:00Z" 1781280000 "s" "1" "Write" "src/a.py" "$ti" 4000 true "")
+	r2=$(lineage_build_record "CID-B" "2026-06-12T00:00:01Z" 1781280001 "s" "2" "Write" "src/a.py" "$ti" 4000 true "")
+	lineage_append "$KEY" "$r1"
+	lineage_append "$KEY" "$r2"
+	local path
+	path=$(lineage_record_path "$KEY")
+	[ -f "$path" ]
+	[ "$(wc -l < "$path")" -eq 2 ]
+	[ "$(jq -rs '.[0].change_id' "$path")" = "CID-A" ]
+	[ "$(jq -rs '.[1].change_id' "$path")" = "CID-B" ]
+}
+
+@test "redaction disabled keeps the raw snippet" {
+	local ti rec
+	ti=$(jq -nc '{file_path:"x", content:"plain text body"}')
+	rec=$(lineage_build_record "CID5" "2026-06-12T00:00:00Z" 1781280000 "s" "1" "Write" "x" "$ti" 4000 false "")
+	[ "$(jq -r '.added_snippets[0]' <<<"$rec")" = "plain text body" ]
+}

package/test/bats/lineage-redact.bats

@@ -0,0 +1,63 @@
+#!/usr/bin/env bats
+
+# Secret-shaped strings are assembled at runtime (prefix + filler) so this test
+# file itself contains no literal secret token a scanner would flag.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/lineage"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-redact.sh"
+}
+
+@test "ordinary code passes through unchanged" {
+	local out
+	out=$(printf '%s' "x = 2  # bumped" | lineage_redact 4000 true)
+	[ "$out" = "x = 2  # bumped" ]
+}
+
+@test "an Anthropic-style API key is redacted" {
+	local tok out
+	tok="sk-ant-$(printf 'a%.0s' $(seq 1 28))"
+	out=$(printf '%s' "key=\"${tok}\"" | lineage_redact 4000 true)
+	[[ "$out" == *"[REDACTED:secret]"* ]]
+	[[ "$out" != *"$tok"* ]]
+}
+
+@test "a GitHub-style token is redacted" {
+	local tok out
+	tok="ghp_$(printf '0%.0s' $(seq 1 36))"
+	out=$(printf '%s' "$tok" | lineage_redact 4000 true)
+	[[ "$out" == *"[REDACTED:secret]"* ]]
+	[[ "$out" != *"$tok"* ]]
+}
+
+@test "a KEY=value secret keeps the key but redacts the value" {
+	local val out
+	val=$(printf 'x%.0s' $(seq 1 24))
+	out=$(printf '%s' "API_TOKEN=${val}" | lineage_redact 4000 true)
+	[[ "$out" == *"API_TOKEN="* ]]
+	[[ "$out" == *"[REDACTED:secret]"* ]]
+	[[ "$out" != *"$val"* ]]
+}
+
+@test "redaction is skipped when disabled" {
+	local tok out
+	tok="ghp_$(printf '0%.0s' $(seq 1 36))"
+	out=$(printf '%s' "$tok" | lineage_redact 4000 false)
+	[ "$out" = "$tok" ]
+}
+
+@test "content longer than the cap is truncated with a marker" {
+	local out
+	out=$(printf '%s' "abcdefghij" | lineage_redact 4 true)
+	[[ "$out" == "abcd"* ]]
+	[[ "$out" == *"truncated 6 chars"* ]]
+}
+
+@test "content within the cap is not truncated" {
+	local out
+	out=$(printf '%s' "abcd" | lineage_redact 4 true)
+	[ "$out" = "abcd" ]
+}

package/test/bats/lineage-ulid.bats

@@ -0,0 +1,28 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/lineage"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/lineage-ulid.sh"
+}
+
+@test "lineage_ulid is 26 characters" {
+	run lineage_ulid
+	[ "$status" -eq 0 ]
+	[ "${#output}" -eq 26 ]
+}
+
+@test "lineage_ulid uses only Crockford base32 (no I, L, O, U)" {
+	run lineage_ulid
+	[[ "$output" =~ ^[0-9A-HJKMNP-TV-Z]+$ ]]
+}
+
+@test "two ulids differ" {
+	local a b
+	a=$(lineage_ulid)
+	b=$(lineage_ulid)
+	[ "$a" != "$b" ]
+}