@onlooker-community/ecosystem 0.27.0 → 0.28.1

package/.claude-plugin/marketplace.json

@@ -202,6 +202,19 @@
       "license": "MIT",
       "keywords": ["budget", "cost", "rollup", "multi-session", "accounting", "audit"],
       "tags": ["governance", "observability"]
+    },
+    {
+      "name": "lineage",
+      "source": "./plugins/lineage",
+      "description": "Per-change provenance — answers \"why does this line exist?\". Records session/turn metadata plus a secret-redacted, size-capped snippet for every Edit/Write/MultiEdit at PostToolUse into a per-project change ledger, then traces a file or line back to the change that introduced it by joining records to the transcripts historian preserves. Emits lineage.* events for audit. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["provenance", "blame", "history", "tool-use", "transcript", "audit"],
+      "tags": ["observability", "provenance"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "Observability substrate for Claude Code. Provides the shared $ONLOOKER_DIR storage root (default $HOME/.onlooker), canonical schema-validated event emission, session and tool tracking hooks, and prompt rules. Required by all other Onlooker plugins.",
   "author": {
     "name": "Onlooker Community",

package/.release-please-manifest.json

@@ -1,11 +1,11 @@
 {
-  ".": "0.27.0",
+  ".": "0.28.1",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
   "plugins/cartographer": "0.2.1",
   "plugins/governor": "0.2.1",
-  "plugins/compass": "0.2.0",
+  "plugins/compass": "0.2.1",
   "plugins/scribe": "0.2.1",
   "plugins/counsel": "0.3.1",
   "plugins/warden": "0.2.0",
@@ -13,5 +13,6 @@
   "plugins/curator": "0.1.0",
   "plugins/historian": "0.2.0",
   "plugins/assayer": "1.0.0",
-  "plugins/bursar": "0.1.0"
+  "plugins/bursar": "0.1.0",
+  "plugins/lineage": "0.1.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.28.1](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.28.0...ecosystem-v0.28.1) (2026-06-12)
+
+
+### Bug Fixes
+
+* **compass:** resolve MultiEdit file path from the top-level field ([#85](https://github.com/onlooker-community/ecosystem/issues/85)) ([468abaa](https://github.com/onlooker-community/ecosystem/commit/468abaaad4bef59fe4308bd8887dfcf6d633921a))
+
+## [0.28.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.27.0...ecosystem-v0.28.0) (2026-06-12)
+
+
+### Features
+
+* **lineage:** introduce per-change provenance plugin ([#83](https://github.com/onlooker-community/ecosystem/issues/83)) ([86b00d3](https://github.com/onlooker-community/ecosystem/commit/86b00d3d7393e2b63c5b04d60692fc89f202bf6c))
+
 ## [0.27.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.26.1...ecosystem-v0.27.0) (2026-06-12)
 
 

package/CLAUDE.md

@@ -16,6 +16,7 @@ plugins/
   compass/                    ← pre-write alignment gate (design phase)
   echo/                       ← prompt-change regression detection
   governor/                   ← resource governance and budget enforcement
+  lineage/                    ← per-change provenance ("why does this line exist?")
   tribunal/                   ← multi-agent quality gate (Actor → Jury → Meta-Judge → Gate)
 
 docs/
@@ -40,6 +41,7 @@ scripts/lib/onlooker-event.mjs  ← canonical event builder; all plugins route t
 | warden | PostToolUse (WebFetch, Read), PreToolUse (Write, Edit, MultiEdit, Bash), SessionStart + skill invocation | Scans ingested content for injection; closes a content gate that blocks write-class tools until cleared via `/warden` |
 | assayer | Stop | Verifies the agent's final-message claims against actual command results in the transcript; advisory |
 | bursar | SessionStart, SessionEnd | Rolls each session's spend into a per-project ledger on SessionEnd; surfaces "this project burned $X this week" at SessionStart. Governor is per-session; bursar is the cross-session rollup |
+| lineage | PostToolUse (Edit, Write, MultiEdit) + skill invocation | Records per-change provenance (session_id/turn + redacted, size-capped snippets) into a per-project ledger; `/lineage <file>:<line>` answers "why does this line exist?" by joining records to historian transcripts to recover prompt context |
 
 Plugins communicate by emitting events to the JSONL log — they do not call each other directly. All plugins depend on the ecosystem substrate; no plugin depends on another plugin directly.
 

package/docs/architecture.md

@@ -60,6 +60,10 @@ Findings are stored in `~/.onlooker/cartographer/<project-key>/findings/` and de
 
 [Bursar](../plugins/bursar) is the clearest example of one plugin consuming another's output **through the bus rather than by direct coupling**. Governor tracks spend per session and emits `governor.session.complete`; bursar reads those events at `SessionEnd`, rolls each session's totals into a per-project ledger under `~/.onlooker/bursar/projects/<project-key>/`, and surfaces "this project burned $X this week" at the next `SessionStart`. It never imports governor's code — if governor is disabled the events simply aren't there, and bursar degrades to a session count. This is the dependency model working as intended: the cross-session rollup is a separate, independently installable plugin that observes governor's event stream.
 
+### Lineage
+
+[Lineage](../plugins/lineage) is the provenance graph — it answers "why does this line exist?" by **joining its own tool-use records to another plugin's transcript store**. On `PostToolUse` it records each `Edit`/`Write`/`MultiEdit` (content-anchored, secret-redacted) into a per-project ledger under `~/.onlooker/lineage/<project-key>/`. The originating prompt is resolved lazily at query time: the `/lineage` skill reads the change ledger, content-anchors a line to the change that introduced it, and joins to [historian](../plugins/historian)'s durable per-session chunks (`start_turn_index`/`end_turn_index`) to recover the conversation context — falling back to the live transcript, then to "unavailable." Historian is the join target precisely because it persists transcripts long after the ephemeral `transcript_path` is gone; lineage stays decoupled and degrades gracefully when historian is absent.
+
 ### Plugin dependency model
 
 All plugins depend on `ecosystem`. No plugin depends on another plugin at runtime. This means:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -19,14 +19,14 @@
     "onlooker-install": "install.sh"
   },
   "dependencies": {
-    "@onlooker-community/schema": "^2.7.0"
+    "@onlooker-community/schema": "^2.8.0"
   },
   "scripts": {
     "postinstall": "echo '\\n  onlooker-ecosystem installed!\\n  Run: npx onlooker-install typescript\\n  Docs: https://github.com/onlooker-community/ecosystem\\n'",
     "test": "npm run test:bats && npm run test:schema",
     "test:bats": "bats test/bats",
     "test:schema": "node --test test/node/*.test.mjs",
-    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh plugins/archivist/scripts/hooks/*.sh plugins/archivist/scripts/lib/*.sh plugins/tribunal/scripts/hooks/*.sh plugins/tribunal/scripts/lib/*.sh plugins/echo/scripts/hooks/*.sh plugins/echo/scripts/lib/*.sh plugins/governor/scripts/hooks/*.sh plugins/governor/scripts/lib/*.sh plugins/compass/scripts/hooks/*.sh plugins/compass/scripts/lib/*.sh plugins/scribe/scripts/hooks/*.sh plugins/scribe/scripts/lib/*.sh plugins/counsel/scripts/hooks/*.sh plugins/counsel/scripts/lib/*.sh plugins/warden/scripts/hooks/*.sh plugins/warden/scripts/lib/*.sh plugins/librarian/scripts/hooks/*.sh plugins/librarian/scripts/lib/*.sh plugins/curator/scripts/hooks/*.sh plugins/curator/scripts/lib/*.sh plugins/historian/scripts/hooks/*.sh plugins/historian/scripts/lib/*.sh plugins/assayer/scripts/hooks/*.sh plugins/assayer/scripts/lib/*.sh plugins/cartographer/scripts/hooks/*.sh plugins/cartographer/scripts/lib/*.sh plugins/bursar/scripts/hooks/*.sh plugins/bursar/scripts/lib/*.sh",
+    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh plugins/archivist/scripts/hooks/*.sh plugins/archivist/scripts/lib/*.sh plugins/tribunal/scripts/hooks/*.sh plugins/tribunal/scripts/lib/*.sh plugins/echo/scripts/hooks/*.sh plugins/echo/scripts/lib/*.sh plugins/governor/scripts/hooks/*.sh plugins/governor/scripts/lib/*.sh plugins/compass/scripts/hooks/*.sh plugins/compass/scripts/lib/*.sh plugins/scribe/scripts/hooks/*.sh plugins/scribe/scripts/lib/*.sh plugins/counsel/scripts/hooks/*.sh plugins/counsel/scripts/lib/*.sh plugins/warden/scripts/hooks/*.sh plugins/warden/scripts/lib/*.sh plugins/librarian/scripts/hooks/*.sh plugins/librarian/scripts/lib/*.sh plugins/curator/scripts/hooks/*.sh plugins/curator/scripts/lib/*.sh plugins/historian/scripts/hooks/*.sh plugins/historian/scripts/lib/*.sh plugins/assayer/scripts/hooks/*.sh plugins/assayer/scripts/lib/*.sh plugins/cartographer/scripts/hooks/*.sh plugins/cartographer/scripts/lib/*.sh plugins/bursar/scripts/hooks/*.sh plugins/bursar/scripts/lib/*.sh plugins/lineage/scripts/hooks/*.sh plugins/lineage/scripts/lib/*.sh",
     "lint:references": "node scripts/lint/check-references.mjs",
     "lint:manifests": "node scripts/lint/check-manifests.mjs",
     "coverage:node": "node scripts/coverage/run-coverage.mjs",

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

@@ -1,6 +1,6 @@
 {
   "name": "compass",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Pre-write intent clarity gate. Intercepts write-class tool calls and requires a confidence threshold before allowing them to proceed. Evaluates the pending write against the prior assistant turn as context to avoid false positives on question-answer turns. Builds on the Onlooker ecosystem plugin.",
   "author": {
     "name": "Onlooker Community",

package/plugins/compass/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.1](https://github.com/onlooker-community/ecosystem/compare/compass-v0.2.0...compass-v0.2.1) (2026-06-12)
+
+
+### Bug Fixes
+
+* **compass:** resolve MultiEdit file path from the top-level field ([#85](https://github.com/onlooker-community/ecosystem/issues/85)) ([468abaa](https://github.com/onlooker-community/ecosystem/commit/468abaaad4bef59fe4308bd8887dfcf6d633921a))
+
 ## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/compass-v0.1.0...compass-v0.2.0) (2026-06-01)
 
 

package/plugins/compass/scripts/hooks/compass-pre-tool-use.sh

@@ -65,14 +65,19 @@ case "$TOOL_NAME" in
 		OPERATION="edit"
 		;;
 	MultiEdit)
-		# For MultiEdit, use the first file path and a summary as context.
+		# MultiEdit applies to one file via a top-level file_path; fall back to
+		# the first edit's path for any nested shape.
 		FILE_PATH=$(printf '%s' "$INPUT" \
-			| jq -r '.tool_input.edits[0].file_path // ""' 2>/dev/null) || FILE_PATH=""
+			| jq -r '.tool_input.file_path // .tool_input.edits[0].file_path // ""' 2>/dev/null) || FILE_PATH=""
 		_edit_count=$(printf '%s' "$INPUT" \
 			| jq '.tool_input.edits | length' 2>/dev/null) || _edit_count="?"
+		# Combine the top-level path with any per-edit paths, drop blanks/nulls.
 		_file_list=$(printf '%s' "$INPUT" \
-			| jq -r '[.tool_input.edits[].file_path] | unique | join(", ")' 2>/dev/null) \
-			|| _file_list="(multiple files)"
+			| jq -r '([.tool_input.file_path] + [.tool_input.edits[]?.file_path] | map(select(. != null and . != "")) | unique) | join(", ")' 2>/dev/null) \
+			|| _file_list=""
+		[[ -z "$_file_list" ]] && _file_list="$FILE_PATH"
+		# Both blank (a MultiEdit with no resolvable path) — keep the context legible.
+		[[ -z "$_file_list" ]] && _file_list="(unknown)"
 		CONTEXT="MultiEdit: ${_edit_count} edit(s) across: ${_file_list}"
 		OPERATION="multi_edit"
 		;;

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

@@ -0,0 +1,14 @@
+{
+  "name": "lineage",
+  "version": "0.1.0",
+  "description": "Per-change provenance for the Onlooker ecosystem. Records session/turn metadata plus a secret-redacted, size-capped snippet for every Edit/Write/MultiEdit at PostToolUse, then answers \"why does this line exist?\" via /lineage by joining change records to historian-preserved transcripts. Emits lineage.* events for audit. Builds on the Onlooker ecosystem plugin.",
+  "author": {
+    "name": "Onlooker Community",
+    "url": "https://onlooker.dev"
+  },
+  "homepage": "https://onlooker.dev",
+  "repository": "https://github.com/onlooker-community/ecosystem",
+  "license": "MIT",
+  "skills": ["./skills/lineage"],
+  "agents": []
+}

package/plugins/lineage/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0](https://github.com/onlooker-community/ecosystem/compare/lineage-v0.0.1...lineage-v0.1.0) (2026-06-12)
+
+
+### Features
+
+* **lineage:** introduce per-change provenance plugin ([#83](https://github.com/onlooker-community/ecosystem/issues/83)) ([86b00d3](https://github.com/onlooker-community/ecosystem/commit/86b00d3d7393e2b63c5b04d60692fc89f202bf6c))
+

package/plugins/lineage/README.md

@@ -0,0 +1,133 @@
+# Lineage
+
+Per-change provenance for the Onlooker ecosystem — "why does this line exist?"
+
+Git records *what* changed and scribe records a session's *intent*, but nothing
+connects a **specific piece of code** to the prompt, agent, and session that
+produced it. Lineage records provenance for every `Edit`/`Write`/`MultiEdit` at
+`PostToolUse`, then answers `/lineage <file>:<line>` by joining its change records
+to the transcripts [historian](../historian) preserves.
+
+Lineage is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker
+observability substrate (`~/.onlooker/`) is present.
+
+## How it works
+
+| Hook | Matcher | What Lineage does |
+|------|---------|-------------------|
+| `PostToolUse` | `Edit`, `Write`, `MultiEdit` | Derives the project key from `cwd`, reads the current turn from the session tracker, extracts the change's added content, redacts secrets + caps size, and appends one record to the per-project change ledger. Emits a lean `lineage.change.recorded` (metadata + digest, never the content). Skips disabled sessions, ignored paths, and files outside the repo. |
+
+The `/lineage` skill is the query side: it reads the ledger and resolves each
+change's originating prompt at query time. It makes no LLM call.
+
+### Content-anchored provenance
+
+Lineage records the **added content** of each change (redacted, capped at
+`max_snippet_chars`). To answer "why does line N exist?", it reads the current
+line's text and finds the most recent change whose added content contains it.
+This is honest about what it is: *what change introduced this content, and why* —
+not a git-blame-exact line mapping. If later edits move or rewrite the line, the
+match is the most recent change that introduced the matching text.
+
+### The historian join
+
+Lineage records only `session_id` + `turn` (+ a `transcript_path` pointer) on the
+hot path — never the prompt. The prompt is resolved lazily at query time:
+
+1. **historian** — read the session's durable chunks at
+   `~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl` and take the
+   chunk whose turn range contains the change's turn (tolerant: nearest preceding,
+   else the last chunk). This is the preferred source because historian persists
+   transcripts long after the live `transcript_path` is gone.
+2. **transcript** — fall back to the live `transcript_path` (the turn-th user
+   message).
+3. **none** — neither available; report the change without a prompt.
+
+The content match — not the turn — is the precise provenance key; the prompt is
+best-effort context, since historian's turn indices need not line up exactly with
+the substrate's turn counter.
+
+## Activation
+
+Lineage is **off by default**. Enable it per-project in `.claude/settings.json`:
+
+```json
+{
+  "lineage": {
+    "enabled": true
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json`. While disabled, the hook skips silently
+and no ledger is written.
+
+## Configuration
+
+All keys are optional. Unset keys fall back to the plugin's `config.json` defaults.
+
+```json
+{
+  "lineage": {
+    "enabled": false,
+    "max_snippet_chars": 4000,
+    "redact_secrets": true,
+    "ignore_globs": ["**/.git/**", "**/node_modules/**", "**/dist/**", "**/*.lock"],
+    "prompt_source": "historian_then_transcript"
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `false` | Must be `true` for recording, querying, or event emission to run. |
+| `max_snippet_chars` | `4000` | Cap on the added-content snippet stored per change. |
+| `redact_secrets` | `true` | Scrub secret-shaped substrings (AWS/GitHub/Anthropic/OpenAI keys, bearer tokens, KEY=value secrets) before storing a snippet. |
+| `ignore_globs` | `[".git", "node_modules", "dist", "*.lock"]` | Paths matching these are not recorded. Supports `**/<dir>/**` (path segment) and `**/*.<ext>` (suffix) shapes. |
+| `prompt_source` | `"historian_then_transcript"` | Prompt-resolution strategy: `historian_then_transcript`, `historian_only`, or `transcript_only`. |
+
+Config resolves in three layers, latest wins: plugin `config.json` →
+`~/.claude/settings.json` → `<repo>/.claude/settings.json`.
+
+## The `/lineage` query
+
+| Invocation | Answers |
+|------------|---------|
+| `/lineage <file>` | Full change history for the file, newest first, each with its resolved prompt context. |
+| `/lineage <file>:<line>` or `/lineage <file> --line N` | Which change introduced the content currently on line N — with the prompt/agent/session behind it. |
+| `/lineage <file> --grep <text>` | Which change introduced content matching `<text>`. |
+| `/lineage --status` | Ledger stats for the project (changes recorded, files touched). |
+
+## Storage layout
+
+```text
+~/.onlooker/lineage/<project-key>/
+├── changes.jsonl        # append-only, one change record per line
+└── changes.jsonl.lock   # write lock
+```
+
+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 added content lives only in this ledger;
+the bus event carries metadata and the `content_sha256` digest, never the content.
+
+Lineage honors `$ONLOOKER_DIR`; it never hardcodes `~/.onlooker`, so the test
+suite's isolated temp home is respected.
+
+## Events emitted
+
+Lineage emits the canonical `lineage.*` surface from
+[`@onlooker-community/schema`](https://github.com/onlooker-community/schema) v2.8.0+.
+
+| Event | When |
+|-------|------|
+| `lineage.change.recorded` | At `PostToolUse`, after a change is appended to the ledger. Carries `project_key`, `session_id`, `file_path`, `tool`, `operation`, `change_id`, and metadata (`lines_added`/`lines_removed`/`bytes`/`edit_count`/`content_sha256`); no content. |
+| `lineage.query.answered` | When `/lineage` answers. Carries `project_key`, `file_path`, `matches`, and (for line queries) `line` and `resolved_via`. |
+
+## Requirements
+
+- The `ecosystem` plugin installed (for the `~/.onlooker/` substrate and canonical event emission).
+- The [`historian`](../historian) plugin enabled, for the most reliable prompt resolution. Without it, lineage falls back to the live transcript, then to "prompt unavailable."
+- `jq` for JSON manipulation.
+- `node` for canonical-event emission.
+- `python3` for secret redaction (the same dependency historian uses for sanitizing).

package/plugins/lineage/config.json

@@ -0,0 +1,11 @@
+{
+  "plugin_name": "lineage",
+  "storage_path": "~/.onlooker",
+  "lineage": {
+    "enabled": false,
+    "max_snippet_chars": 4000,
+    "redact_secrets": true,
+    "ignore_globs": ["**/.git/**", "**/node_modules/**", "**/dist/**", "**/*.lock"],
+    "prompt_source": "historian_then_transcript"
+  }
+}

package/plugins/lineage/hooks/hooks.json

@@ -0,0 +1,33 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/lineage-post-tool-use.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/lineage-post-tool-use.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/lineage-post-tool-use.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/lineage/scripts/hooks/lineage-post-tool-use.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Lineage PostToolUse hook (Edit / Write / MultiEdit).
+#
+# Records per-change provenance into the per-project change ledger and emits a
+# lean lineage.change.recorded event. Kept cheap: metadata + a redacted,
+# size-capped snippet of the added content + a digest — no transcript parsing
+# (the prompt is resolved lazily at /lineage query time).
+#
+# Hook contract: always exits 0; never blocks the tool. Skips silently when
+# disabled, when the path is ignored, or when the file is outside the repo.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/portable-lock.sh
+source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+# shellcheck source=../lib/lineage-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-config.sh"
+# shellcheck source=../lib/lineage-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-events.sh"
+# shellcheck source=../lib/lineage-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-project-key.sh"
+# shellcheck source=../lib/lineage-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-ulid.sh"
+# shellcheck source=../lib/lineage-redact.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-redact.sh"
+# shellcheck source=../lib/lineage-record.sh
+source "${PLUGIN_ROOT}/scripts/lib/lineage-record.sh"
+
+INPUT=$(cat)
+_done() { exit 0; }
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || TOOL=""
+TOOL_INPUT=$(printf '%s' "$INPUT" | jq -c '.tool_input // {}' 2>/dev/null) || TOOL_INPUT="{}"
+TOOL_USE_ID=$(printf '%s' "$INPUT" | jq -r '.tool_use_id // ""' 2>/dev/null) || TOOL_USE_ID=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+
+case "$TOOL" in
+	Edit | Write | MultiEdit) ;;
+	*) _done ;;
+esac
+
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+REPO_ROOT=$(lineage_project_repo_root "$CWD")
+lineage_config_load "$REPO_ROOT"
+lineage_config_enabled || _done
+
+PROJECT_KEY=$(lineage_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && _done
+
+FILE_PATH=""
+case "$TOOL" in
+	MultiEdit)
+		# MultiEdit applies to one file via a top-level file_path; some shapes
+		# nest file_path per edit, so fall back to the first edit's.
+		FILE_PATH=$(printf '%s' "$TOOL_INPUT" | jq -r '.file_path // .edits[0].file_path // ""' 2>/dev/null) || FILE_PATH=""
+		# If edits carry distinct per-file paths spanning more than one file,
+		# skip to avoid misattribution. (Future: split into one record per file.)
+		unique_count=$(printf '%s' "$TOOL_INPUT" | jq -r '[.edits[]?.file_path // empty] | unique | length' 2>/dev/null) || unique_count=0
+		[[ "${unique_count:-0}" -gt 1 ]] && _done
+		;;
+	*)
+		FILE_PATH=$(printf '%s' "$TOOL_INPUT" | jq -r '.file_path // .path // ""' 2>/dev/null) || FILE_PATH=""
+		;;
+esac
+[[ -z "$FILE_PATH" ]] && _done
+
+# Skip ignored paths. Supports the common glob shapes in config:
+#   **/<dir>/**  → path-segment match ;  **/*.<ext> → suffix match.
+_lineage_ignored() {
+	local path="$1" glob core
+	while IFS= read -r glob; do
+		[[ -z "$glob" ]] && continue
+		core="$glob"
+		core="${core#\*\*/}"
+		core="${core%/\*\*}"
+		case "$core" in
+			\*.*) [[ "$path" == *"${core#\*}" ]] && return 0 ;;
+			*) [[ "/$path/" == *"/$core/"* ]] && return 0 ;;
+		esac
+	done < <(lineage_config_ignore_globs)
+	return 1
+}
+_lineage_ignored "$FILE_PATH" && _done
+
+# Skip files outside the repo (best-effort). Resolve the file's directory to a
+# real path so the prefix test survives symlinked roots (e.g. macOS /var →
+# /private/var, where REPO_ROOT is already realpath-resolved).
+if [[ -n "$REPO_ROOT" && "$FILE_PATH" == /* ]]; then
+	_file_dir=$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && pwd -P) || _file_dir=""
+	if [[ -n "$_file_dir" && "$_file_dir" != "$REPO_ROOT" && "$_file_dir"/ != "$REPO_ROOT"/* ]]; then
+		_done
+	fi
+fi
+
+# Turn number (best-effort) from the substrate session tracker.
+TURN=""
+TRACKER="${ONLOOKER_DIR:-$HOME/.onlooker}/session-trackers/${SESSION_ID}"
+[[ -n "$SESSION_ID" && -f "$TRACKER" ]] && TURN=$(jq -r '.turn_number // empty' "$TRACKER" 2>/dev/null)
+
+MAX_CHARS=$(lineage_config_max_snippet_chars)
+DO_REDACT=true
+lineage_config_redact_enabled || DO_REDACT=false
+CHANGE_ID=$(lineage_ulid)
+TS=$(lineage_now_iso)
+TS_EPOCH=$(lineage_now_epoch)
+
+RECORD=$(lineage_build_record "$CHANGE_ID" "$TS" "$TS_EPOCH" "$SESSION_ID" "$TURN" \
+	"$TOOL" "$FILE_PATH" "$TOOL_INPUT" "$MAX_CHARS" "$DO_REDACT" "$TRANSCRIPT_PATH")
+[[ -z "$RECORD" ]] && _done
+
+if lineage_append "$PROJECT_KEY" "$RECORD"; then
+	# Lean bus event: metadata + digest only — never the added content.
+	EV=$(printf '%s' "$RECORD" | jq -c --arg pk "$PROJECT_KEY" --arg tuid "$TOOL_USE_ID" '
+		{
+			project_key: $pk, session_id: .session_id, file_path: .file_path,
+			tool: .tool, operation: .operation, change_id: .change_id,
+			lines_added: .lines_added, lines_removed: .lines_removed,
+			bytes: .bytes, edit_count: .edit_count, content_sha256: .content_sha256
+		}
+		+ (if .turn != null then {turn: .turn} else {} end)
+		+ (if $tuid != "" then {tool_use_id: $tuid} else {} end)
+	' 2>/dev/null)
+	[[ -n "$EV" ]] && lineage_emit_event "lineage.change.recorded" "$EV" "$SESSION_ID" || true
+fi
+
+_done

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

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# Config resolution for lineage.
+#
+# Reads three layers, latest wins:
+#   1. plugins/lineage/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   lineage_config_load <repo_root>     # populates _LINEAGE_CONFIG (JSON)
+#   lineage_config_get <jq-path>        # echoes string value (empty if unset)
+#   lineage_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   lineage_config_enabled              # 0 if lineage.enabled is true
+#   lineage_config_max_snippet_chars    # echoes the snippet cap (default 4000)
+#   lineage_config_redact_enabled       # 0 unless redact_secrets is false
+#   lineage_config_prompt_source        # echoes the prompt-source strategy
+#   lineage_config_ignore_globs         # echoes ignore globs, one per line
+
+_LINEAGE_CONFIG="{}"
+
+lineage_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	local repo_settings=""
+	[[ -n "$repo_root" ]] && repo_settings="${repo_root}/.claude/settings.json"
+
+	for file in "${home_dir}/.claude/settings.json" "$repo_settings"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ lineage: (.lineage // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		local attempt
+		if attempt=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) && [[ -n "$attempt" ]]; then
+			merged="$attempt"
+		fi
+	done
+
+	_LINEAGE_CONFIG="$merged"
+}
+
+lineage_config_get() {
+	local path="$1"
+	printf '%s' "$_LINEAGE_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+lineage_config_get_json() {
+	local path="$1"
+	printf '%s' "$_LINEAGE_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+lineage_config_enabled() {
+	local v
+	v=$(lineage_config_get '.lineage.enabled')
+	[[ "$v" == "true" ]]
+}
+
+lineage_config_max_snippet_chars() {
+	local v
+	v=$(lineage_config_get '.lineage.max_snippet_chars')
+	printf '%s' "${v:-4000}"
+}
+
+lineage_config_redact_enabled() {
+	# Default on. jq's `//` treats a literal `false` as empty, so read the raw
+	# JSON value and only disable on an explicit false.
+	local v
+	v=$(lineage_config_get_json '.lineage.redact_secrets')
+	[[ "$v" != "false" ]]
+}
+
+lineage_config_prompt_source() {
+	local v
+	v=$(lineage_config_get '.lineage.prompt_source')
+	printf '%s' "${v:-historian_then_transcript}"
+}
+
+lineage_config_ignore_globs() {
+	printf '%s' "$_LINEAGE_CONFIG" | jq -r '.lineage.ignore_globs[]? // empty' 2>/dev/null
+}