@onlooker-community/ecosystem 0.27.0 → 0.28.1

package/plugins/lineage/skills/lineage/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: lineage
+description: Answer "why does this line exist?" — trace a file, or a specific line, back to the change, prompt, agent, and session that produced it. Reads lineage's per-project change ledger and joins it to the transcripts historian preserves. Modes — /lineage <file> (change history), /lineage <file>:<line> or --line N (single-line provenance), /lineage <file> --grep <text> (content search), /lineage --status (ledger stats). Use when the user asks who/what/why introduced code in a file, or invokes /lineage.
+---
+
+# Lineage Skill
+
+`/lineage` reads the per-project change ledger that the PostToolUse hook records
+and resolves each change's originating prompt by joining to historian's durable
+session transcripts (falling back to the live transcript). It answers
+"why does this line exist?" without an LLM call — pure read, join, and render.
+
+## Setup
+
+Run once. Sources the plugin helpers, loads config, and resolves project context.
+
+```bash
+set -uo pipefail
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+source "$PLUGIN_ROOT/scripts/lib/portable-lock.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-config.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-events.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-project-key.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-redact.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-record.sh"
+source "$PLUGIN_ROOT/scripts/lib/lineage-query.sh"
+
+REPO_ROOT=$(lineage_project_repo_root "$(pwd)")
+lineage_config_load "$REPO_ROOT"
+if ! lineage_config_enabled; then
+  echo "Lineage is disabled. Set lineage.enabled=true in .claude/settings.json to enable."
+  exit 0
+fi
+PROJECT_KEY=$(lineage_project_key "$(pwd)")
+if [[ -z "$PROJECT_KEY" ]]; then
+  echo "No project key — lineage needs a git repository (remote or root) to scope its ledger."
+  exit 0
+fi
+PROMPT_SOURCE=$(lineage_config_prompt_source)
+QSID="${CLAUDE_SESSION_ID:-lineage-query}"
+```
+
+## Invocation Modes
+
+### `/lineage <file>` — change history (default)
+
+Set `FILE` to the path the user named, then run. (Repo-relative paths are
+resolved against the repo root.)
+
+```bash
+FILE="REPLACE_WITH_FILE"
+[[ "$FILE" != /* && -n "$REPO_ROOT" ]] && FILE="$REPO_ROOT/$FILE"
+
+echo "## Lineage — change history for \`$FILE\`"
+count=0
+while IFS= read -r rec; do
+  [[ -z "$rec" ]] && continue
+  count=$((count + 1))
+  ts=$(jq -r '.ts' <<<"$rec"); sid=$(jq -r '.session_id' <<<"$rec")
+  turn=$(jq -r '.turn // ""' <<<"$rec"); tool=$(jq -r '.tool' <<<"$rec")
+  la=$(jq -r '.lines_added' <<<"$rec"); lr=$(jq -r '.lines_removed' <<<"$rec")
+  tp=$(jq -r '.transcript_path // ""' <<<"$rec")
+  resolved=$(lineage_resolve_prompt "$PROJECT_KEY" "$sid" "$turn" "$tp" "$PROMPT_SOURCE")
+  prompt=$(jq -r '.prompt' <<<"$resolved"); via=$(jq -r '.resolved_via' <<<"$resolved")
+  echo ""
+  echo "### ${ts} · ${tool} (+${la}/-${lr}) · session ${sid}${turn:+ · turn ${turn}}"
+  if [[ -n "$prompt" ]]; then
+    echo "Prompt context (${via}):"; echo ""
+    printf '%s\n' "$prompt" | head -c 600 | sed 's/^/> /'
+  else
+    echo "_Prompt unavailable (${via})._"
+  fi
+done < <(lineage_changes_for_file "$PROJECT_KEY" "$FILE")
+[[ "$count" -eq 0 ]] && { echo ""; echo "No recorded changes for this file (it may predate lineage)."; }
+
+lineage_emit_event "lineage.query.answered" \
+  "$(jq -nc --arg pk "$PROJECT_KEY" --arg f "$FILE" --argjson m "$count" \
+     '{project_key:$pk, file_path:$f, matches:$m}')" "$QSID" || true
+```
+
+### `/lineage <file>:<line>` (or `--line N`) — single-line provenance
+
+Set `FILE` and `LINE`, then run. Reads the current line's text and content-anchors
+it to the change that introduced it.
+
+```bash
+FILE="REPLACE_WITH_FILE"; LINE="REPLACE_WITH_LINE_NUMBER"
+[[ "$FILE" != /* && -n "$REPO_ROOT" ]] && FILE="$REPO_ROOT/$FILE"
+
+line_text=$(sed -n "${LINE}p" "$FILE" 2>/dev/null)
+needle=$(printf '%s' "$line_text" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+
+echo "## Lineage — why does \`$FILE\`:${LINE} exist?"
+echo ""
+echo "Line ${LINE}: \`${line_text}\`"
+
+rec=$(lineage_match_line "$PROJECT_KEY" "$FILE" "$needle")
+via="none"; matches=0
+if [[ -z "$rec" ]]; then
+  echo ""
+  echo "No recorded change introduced this content (it may predate lineage, or the line moved since it was written)."
+else
+  matches=1
+  ts=$(jq -r '.ts' <<<"$rec"); sid=$(jq -r '.session_id' <<<"$rec")
+  turn=$(jq -r '.turn // ""' <<<"$rec"); tool=$(jq -r '.tool' <<<"$rec")
+  tp=$(jq -r '.transcript_path // ""' <<<"$rec")
+  resolved=$(lineage_resolve_prompt "$PROJECT_KEY" "$sid" "$turn" "$tp" "$PROMPT_SOURCE")
+  prompt=$(jq -r '.prompt' <<<"$resolved"); via=$(jq -r '.resolved_via' <<<"$resolved")
+  echo ""
+  echo "Introduced ${ts} by a ${tool} in session ${sid}${turn:+ (turn ${turn})}."
+  if [[ -n "$prompt" ]]; then
+    echo ""; echo "Prompt context (${via}):"; echo ""
+    printf '%s\n' "$prompt" | sed 's/^/> /'
+  else
+    echo "_Prompt unavailable (${via})._"
+  fi
+fi
+
+lineage_emit_event "lineage.query.answered" \
+  "$(jq -nc --arg pk "$PROJECT_KEY" --arg f "$FILE" --argjson m "$matches" \
+     --argjson ln "${LINE:-0}" --arg via "$via" \
+     '{project_key:$pk, file_path:$f, matches:$m, line:$ln, resolved_via:$via}')" "$QSID" || true
+```
+
+### `/lineage <file> --grep <text>` — content search
+
+Same as the line mode, but set `needle` to the user's search text instead of
+reading a line from the file:
+
+```bash
+FILE="REPLACE_WITH_FILE"; needle="REPLACE_WITH_TEXT"
+[[ "$FILE" != /* && -n "$REPO_ROOT" ]] && FILE="$REPO_ROOT/$FILE"
+rec=$(lineage_match_line "$PROJECT_KEY" "$FILE" "$needle")
+# …render as in the line mode…
+```
+
+### `/lineage --status` — ledger stats
+
+```bash
+LEDGER=$(lineage_record_path "$PROJECT_KEY")
+echo "## Lineage status"
+echo "- Project key: ${PROJECT_KEY}"
+echo "- Ledger: ${LEDGER}"
+if [[ -f "$LEDGER" ]]; then
+  total=$(wc -l < "$LEDGER" | tr -d ' ')
+  files=$(jq -r '.file_path' "$LEDGER" 2>/dev/null | sort -u | grep -c '')
+  echo "- Changes recorded: ${total} across ${files} file(s)"
+else
+  echo "- No changes recorded yet. Make some Edit/Write changes with lineage enabled."
+fi
+```
+
+## Notes
+
+- Provenance is **content-anchored**: a line is matched to the change whose added
+  content contains it. If later edits moved or rewrote the line, the match is the
+  most recent change that introduced the matching text — not a git-blame-exact
+  mapping.
+- The prompt is resolved lazily: historian's preserved per-session chunks first
+  (durable across transcript cleanup), then the live `transcript_path`, then
+  "unavailable." Install and enable historian for the most reliable prompts.
+- Storage, project keying, and event emission match the other ecosystem plugins;
+  everything is scoped by project key and honors `$ONLOOKER_DIR`.

package/release-please-config.json

@@ -238,6 +238,22 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/lineage": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "lineage",
+      "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/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")" = "" ]
+}