@onlooker-community/ecosystem 0.27.0 → 0.28.0

package/plugins/lineage/scripts/lib/lineage-project-key.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Project key derivation for lineage.
+#
+# Mirrors the archivist/tribunal project-key scheme so the plugins partition
+# storage identically. A project key is a stable 12-char hex identifier that
+# survives:
+#   - local rename of the repo directory
+#   - cloning the same repo to a different path on the same machine
+#   - moving the repo between machines (as long as the git remote is preserved)
+#   - worktrees (a worktree shares its parent repo's key)
+#
+# Resolution order:
+#   1. SHA256(`git remote get-url origin`) — preferred, machine-portable
+#   2. SHA256(realpath of `git rev-parse --show-toplevel`) — fallback for repos
+#      without an origin remote (greenfield local-only work)
+#
+# Returns the first 12 hex chars. Returns empty string if neither resolution
+# path works.
+
+_lineage_sha256_first12() {
+	local input="$1"
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$input" | shasum -a 256 2>/dev/null | cut -c1-12
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$input" | sha256sum 2>/dev/null | cut -c1-12
+	else
+		return 1
+	fi
+}
+
+lineage_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+# Worktree-aware: uses common-dir so worktrees share a key with the main repo.
+lineage_project_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+
+	if ! git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+
+	if [[ -n "$common_dir" && "$common_dir" != /* ]]; then
+		common_dir="$(cd "$cwd" && cd "$common_dir" 2>/dev/null && pwd -P)" || common_dir=""
+	fi
+
+	if [[ -n "$common_dir" && -d "$common_dir" ]]; then
+		toplevel="$(cd "$common_dir/.." 2>/dev/null && pwd -P)" || toplevel=""
+	fi
+
+	if [[ -z "$toplevel" ]]; then
+		toplevel=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || true)
+		[[ -n "$toplevel" ]] && toplevel="$(cd "$toplevel" 2>/dev/null && pwd -P)"
+	fi
+
+	printf '%s' "$toplevel"
+}
+
+# Compute the project key for the given cwd. Prints the key or empty string.
+lineage_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(lineage_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_lineage_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(lineage_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_lineage_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}

package/plugins/lineage/scripts/lib/lineage-query.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Query side of lineage: read the change ledger and resolve prompts.
+#
+# The /lineage skill is a thin wrapper over these functions; the logic lives
+# here so it is unit-testable in bats without driving the skill runtime.
+#
+# Requires lineage-record.sh (for lineage_record_path) and lineage-redact.sh
+# (for capping/scrubbing resolved prompts) sourced beforehand.
+
+# All change records for a file, newest first (one compact JSON per line).
+# Usage: lineage_changes_for_file <project_key> <file_path>
+lineage_changes_for_file() {
+	local key="$1" file="$2"
+	local path
+	path=$(lineage_record_path "$key")
+	[[ -f "$path" ]] || return 0
+	jq -s -c --arg f "$file" \
+		'[ .[] | select(.file_path == $f) ] | reverse | .[]' \
+		"$path" 2>/dev/null
+}
+
+# The newest change whose added content contains <line_text> (substring),
+# i.e. the change that introduced that content. Echoes one record or nothing.
+# Usage: lineage_match_line <project_key> <file_path> <line_text>
+lineage_match_line() {
+	local key="$1" file="$2" needle="$3"
+	local path
+	path=$(lineage_record_path "$key")
+	[[ -f "$path" ]] || return 0
+	# An empty/whitespace needle has no meaningful introducing change.
+	[[ -z "${needle//[[:space:]]/}" ]] && return 0
+	jq -s -c --arg f "$file" --arg t "$needle" '
+		[ .[] | select(.file_path == $f) ] | reverse
+		| map(select(any(.added_snippets[]?; type == "string" and contains($t))))
+		| (.[0] // empty)
+	' "$path" 2>/dev/null
+}
+
+# Resolve the originating prompt for a change. Tries historian's durable
+# per-session chunks first (tolerant turn-range match), then the live
+# transcript, then gives up. Echoes {prompt, resolved_via} as JSON.
+# Usage: lineage_resolve_prompt <project_key> <session_id> <turn> <transcript_path> [prompt_source]
+lineage_resolve_prompt() {
+	local key="$1" sid="$2" turn="$3" transcript_path="$4" source="${5:-historian_then_transcript}"
+	local prompt="" via="none"
+	local onlooker="${ONLOOKER_DIR:-$HOME/.onlooker}"
+
+	# 1) historian: chunk whose [start_turn_index,end_turn_index] contains the
+	#    turn, else nearest preceding, else the last chunk. body_redacted is the
+	#    conversation context historian preserved for that span.
+	if [[ "$source" != "transcript_only" && -n "$key" && -n "$sid" ]]; then
+		local safe_sid hist_file
+		safe_sid=$(printf '%s' "$sid" | tr -cd '[:alnum:]._-')
+		[[ -z "$safe_sid" ]] && safe_sid="unknown"
+		hist_file="${onlooker}/historian/${key}/sessions/${safe_sid}.jsonl"
+		if [[ -f "$hist_file" ]]; then
+			prompt=$(jq -rs --argjson t "${turn:-0}" '
+				( [ .[] | select((.start_turn_index // 0) <= $t and (.end_turn_index // 0) >= $t) ] | .[0] )
+				// ( [ .[] | select((.end_turn_index // 0) <= $t) ] | sort_by(.end_turn_index) | last )
+				// (.[-1] // empty)
+				| (.body_redacted // "")
+			' "$hist_file" 2>/dev/null) || prompt=""
+			[[ -n "$prompt" ]] && via="historian"
+		fi
+	fi
+
+	# 2) transcript fallback: the turn-th user message (1-based), else the last.
+	#    Tolerant of both transcript shapes (.role/.content and .type/.message.content).
+	if [[ -z "$prompt" && "$source" != "historian_only" && -n "$transcript_path" && -f "$transcript_path" ]]; then
+		prompt=$(jq -rs --argjson t "${turn:-0}" '
+			[ .[]
+			  | select((.role // .type) == "user")
+			  | ((.content // .message.content) as $c
+			     | if ($c | type) == "array"
+			       then [ $c[]? | select(.type == "text") | .text ] | join("\n")
+			       else ($c // "") end)
+			] as $u
+			| ($u[($t - 1)] // ($u[-1] // ""))
+		' "$transcript_path" 2>/dev/null) || prompt=""
+		[[ -n "$prompt" ]] && via="transcript"
+	fi
+
+	# Cap + scrub for display (historian bodies are already redacted; this also
+	# scrubs the transcript path and keeps the excerpt short).
+	prompt=$(printf '%s' "$prompt" | lineage_redact 1000 true)
+
+	jq -nc --arg p "$prompt" --arg v "$via" '{prompt: $p, resolved_via: $v}'
+}

package/plugins/lineage/scripts/lib/lineage-record.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Build and append lineage change records.
+#
+# Storage: $ONLOOKER_DIR/lineage/<project-key>/changes.jsonl — append-only, one
+# change per line. Each record:
+#   { change_id, ts, ts_epoch, session_id, turn?, tool, operation, file_path,
+#     lines_added, lines_removed, bytes, edit_count, content_sha256,
+#     added_snippets[], transcript_path }
+#
+# The bus event (lineage.change.recorded) carries metadata + content_sha256
+# only; the added content lives here in the per-project ledger, where the
+# /lineage query content-anchors a line back to the change that introduced it.
+#
+# Requires lineage-redact.sh and portable-lock.sh sourced beforehand.
+
+lineage_record_dir() {
+	local key="${1:-unknown}"
+	local safe
+	safe=$(printf '%s' "$key" | tr -c 'a-zA-Z0-9-' '_')
+	printf '%s/lineage/%s' "${ONLOOKER_DIR:-${HOME}/.onlooker}" "$safe"
+}
+
+lineage_record_path() { printf '%s/changes.jsonl' "$(lineage_record_dir "$1")"; }
+
+lineage_now_iso() { date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || printf ''; }
+lineage_now_epoch() { date +%s 2>/dev/null || printf '0'; }
+
+lineage_sha256() {
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$1" | shasum -a 256 2>/dev/null | cut -d' ' -f1
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$1" | sha256sum 2>/dev/null | cut -d' ' -f1
+	else
+		printf ''
+	fi
+}
+
+# Line count of a text blob (0 for empty). `grep -c ''` counts every line,
+# including a final line with no trailing newline.
+_lineage_count_lines() {
+	[[ -z "$1" ]] && { printf '0'; return 0; }
+	printf '%s' "$1" | grep -c '' 2>/dev/null || printf '0'
+}
+
+# Tool → operation enum (create|overwrite|edit|multi_edit). Write is recorded as
+# a coarse "create"; the create/overwrite distinction is not reliably knowable
+# at PostToolUse and does not affect the provenance answer.
+_lineage_operation() {
+	case "$1" in
+		Edit) printf 'edit' ;;
+		MultiEdit) printf 'multi_edit' ;;
+		Write) printf 'create' ;;
+		*) printf 'edit' ;;
+	esac
+}
+
+# Added / removed content extracted from the tool_input JSON, per tool.
+_lineage_added() {
+	local tool="$1" ti="$2"
+	case "$tool" in
+		Edit) printf '%s' "$ti" | jq -r '.new_string // ""' 2>/dev/null ;;
+		Write) printf '%s' "$ti" | jq -r '.content // ""' 2>/dev/null ;;
+		MultiEdit) printf '%s' "$ti" | jq -r '[.edits[]?.new_string // ""] | join("\n")' 2>/dev/null ;;
+	esac
+}
+
+_lineage_removed() {
+	local tool="$1" ti="$2"
+	case "$tool" in
+		Edit) printf '%s' "$ti" | jq -r '.old_string // ""' 2>/dev/null ;;
+		Write) printf '' ;;
+		MultiEdit) printf '%s' "$ti" | jq -r '[.edits[]?.old_string // ""] | join("\n")' 2>/dev/null ;;
+	esac
+}
+
+# Build a change record JSON (pure — no I/O). Echoes the record.
+# Usage: lineage_build_record <change_id> <ts> <ts_epoch> <session_id> <turn>
+#          <tool> <file_path> <tool_input_json> <max_chars> <do_redact> <transcript_path>
+lineage_build_record() {
+	local change_id="$1" ts="$2" ts_epoch="$3" session_id="$4" turn="$5"
+	local tool="$6" file_path="$7" ti="$8" max_chars="$9" do_redact="${10}" transcript_path="${11}"
+
+	local added removed added_red lines_added lines_removed bytes digest op edit_count
+	added=$(_lineage_added "$tool" "$ti")
+	removed=$(_lineage_removed "$tool" "$ti")
+	lines_added=$(_lineage_count_lines "$added")
+	lines_removed=$(_lineage_count_lines "$removed")
+	bytes=$(printf '%s' "$added" | wc -c | tr -d ' ')
+	digest=$(lineage_sha256 "$added")
+	op=$(_lineage_operation "$tool")
+	edit_count=$(printf '%s' "$ti" | jq -r 'if .edits then (.edits | length) else 1 end' 2>/dev/null) || edit_count=1
+	added_red=$(printf '%s' "$added" | lineage_redact "$max_chars" "$do_redact")
+
+	jq -n \
+		--arg cid "$change_id" --arg ts "$ts" --argjson te "${ts_epoch:-0}" \
+		--arg sid "$session_id" --arg tool "$tool" --arg op "$op" \
+		--arg fp "$file_path" --arg snip "$added_red" --arg tp "$transcript_path" \
+		--argjson la "${lines_added:-0}" --argjson lr "${lines_removed:-0}" \
+		--argjson by "${bytes:-0}" --arg digest "$digest" \
+		--argjson ec "${edit_count:-1}" --arg turn "$turn" \
+		'{
+			change_id: $cid, ts: $ts, ts_epoch: $te,
+			session_id: $sid, tool: $tool, operation: $op, file_path: $fp,
+			lines_added: $la, lines_removed: $lr, bytes: $by,
+			edit_count: $ec, content_sha256: $digest,
+			added_snippets: [$snip], transcript_path: $tp
+		}
+		+ (if $turn != "" then {turn: ($turn | tonumber)} else {} end)' 2>/dev/null
+}
+
+# Append a record to the project ledger under its write lock.
+# Usage: lineage_append <project_key> <record_json>
+lineage_append() {
+	local key="$1" record="$2"
+	[[ -z "$key" || -z "$record" ]] && return 1
+
+	local dir path lock rec_compact
+	dir=$(lineage_record_dir "$key")
+	path="${dir}/changes.jsonl"
+	lock="${path}.lock"
+	mkdir -p "$dir" 2>/dev/null || return 1
+
+	rec_compact=$(printf '%s' "$record" | jq -c . 2>/dev/null) || return 1
+
+	if lock_acquire "$lock" 5; then
+		printf '%s\n' "$rec_compact" >> "$path" 2>/dev/null
+		local ok=$?
+		lock_release "$lock"
+		return "$ok"
+	fi
+	return 1
+}

package/plugins/lineage/scripts/lib/lineage-redact.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Secret redaction + size capping for lineage change snippets.
+#
+# Mirrors the conservative secret patterns in historian-sanitizer.sh (false
+# positives acceptable; false negatives are the failure mode that matters).
+# The heavy lifting runs in an inline python3 block — the same pattern
+# historian uses — because portable case-insensitive regex across BSD/GNU sed
+# is not worth the fragility on a path that handles user code.
+
+# Redact secret-shaped substrings from stdin, then cap to <max_chars>.
+# Usage: printf '%s' "$content" | lineage_redact <max_chars> <redact:true|false>
+lineage_redact() {
+	local max_chars="${1:-4000}"
+	local do_redact="${2:-true}"
+	# Pass the program via -c (not a heredoc on stdin): -c keeps stdin free for
+	# the piped content, so sys.stdin.read() actually receives it.
+	local _prog
+	_prog=$(cat <<'PY'
+import re
+import sys
+
+max_chars = int(sys.argv[1] or "4000")
+do_redact = sys.argv[2] != "false"
+text = sys.stdin.read()
+
+if do_redact:
+    patterns = [
+        re.compile(r"\bAKIA[0-9A-Z]{16}\b"),            # AWS access key id
+        re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"),  # GitHub tokens
+        re.compile(r"\bsk-ant-[A-Za-z0-9_-]{20,}\b"),   # Anthropic API keys
+        re.compile(r"\bsk-[A-Za-z0-9]{20,}\b"),         # OpenAI-style keys
+        re.compile(r"(?i:Bearer)\s+[A-Za-z0-9._\-+/=]{20,}"),  # bearer tokens
+    ]
+    for pat in patterns:
+        text = pat.sub("[REDACTED:secret]", text)
+    # KEY=value or "key": "value" where the key name implies a secret;
+    # preserve the key, redact the value.
+    kv = re.compile(
+        r'([A-Za-z0-9_]*(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD)[A-Za-z0-9_]*"?\s*[:=]\s*"?)\S+',
+        re.IGNORECASE,
+    )
+    text = kv.sub(lambda m: m.group(1) + "[REDACTED:secret]", text)
+
+if len(text) > max_chars:
+    text = text[:max_chars] + "… [truncated %d chars]" % (len(text) - max_chars)
+
+sys.stdout.write(text)
+PY
+)
+	python3 -c "$_prog" "$max_chars" "$do_redact"
+}

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for lineage record 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
+#
+# Copied from plugins/tribunal/scripts/lib/tribunal-ulid.sh and renamed; the
+# ecosystem ships one *_ulid helper per plugin rather than a shared one.
+
+_LINEAGE_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_lineage_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_LINEAGE_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+lineage_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_hex rand_hi rand_lo
+	rand_hex=$(openssl rand -hex 10 2>/dev/null)
+	if [[ -n "$rand_hex" && ${#rand_hex} -eq 20 ]]; then
+		rand_hi=$((16#${rand_hex:0:10}))
+		rand_lo=$((16#${rand_hex:10:10}))
+	else
+		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)))
+	fi
+
+	local ts_part hi_part lo_part
+	ts_part=$(_lineage_ulid_encode "$now_ms" 10)
+	hi_part=$(_lineage_ulid_encode "$rand_hi" 8)
+	lo_part=$(_lineage_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/plugins/lineage/scripts/lib/portable-lock.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# portable-lock.sh — vendored copy of the ecosystem substrate's portable lock.
+#
+# Vendored into the lineage plugin so the per-project ledger's atomic upserts
+# keep working when lineage is installed standalone from the marketplace: the
+# cache layout (~/.claude/plugins/cache/<owner>/lineage/<version>/) does not
+# include the ecosystem repo's top-level scripts/lib/. Without a local copy,
+# lock_acquire would be undefined and concurrent PostToolUse appends (e.g.
+# from parallel subagents) could clobber the change ledger. This mirrors the
+# per-plugin vendoring of lineage-ulid.sh and friends.
+# Keep in sync with scripts/lib/portable-lock.sh at the repo root.
+#
+# Portable advisory file locking via mkdir() atomicity.
+#
+# Replaces flock(1), which ships with util-linux on Linux but is not present
+# in stock macOS. This matters because the Onlooker hooks run on user
+# machines, not just in CI: a macOS user without util-linux would otherwise
+# see concurrent writes to $ONLOOKER_DIR silently clobber each other.
+#
+# mkdir() is atomic on POSIX local filesystems, which is the only place
+# $ONLOOKER_DIR ever lives. Network filesystems (NFS) do not guarantee
+# atomicity, but Claude Code state is local-only.
+#
+# Usage:
+#   lock_acquire "/path/to/file.lock" [timeout_seconds=5]
+#   # ... critical section ...
+#   lock_release "/path/to/file.lock"
+#
+# Avoid associative arrays so bash 3.2 (macOS default) keeps working.
+
+# Acquire an exclusive lock at LOCKPATH. Returns 0 on success, 1 on timeout.
+lock_acquire() {
+	local lockpath="${1:-}"
+	local timeout="${2:-5}"
+	[[ -z "$lockpath" ]] && return 1
+
+	local lockdir="${lockpath}.d"
+	local waited=0
+	# Poll at 10 Hz so a 5s timeout = 50 attempts.
+	local max_iter=$((timeout * 10))
+	while ! mkdir "$lockdir" 2>/dev/null; do
+		if ((waited >= max_iter)); then
+			return 1
+		fi
+		# `sleep 0.1` works on Linux + macOS; the `|| sleep 1` is a paranoid
+		# fallback for embedded shells that only accept integer seconds.
+		sleep 0.1 2>/dev/null || sleep 1
+		waited=$((waited + 1))
+	done
+	return 0
+}
+
+# Release the lock previously acquired for LOCKPATH. Safe to call when the
+# lock is not held (no-op in that case).
+lock_release() {
+	local lockpath="${1:-}"
+	[[ -z "$lockpath" ]] && return 0
+	rmdir "${lockpath}.d" 2>/dev/null || true
+}

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"