lineage

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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/onlooker-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=$(onlooker_project_repo_root "$(pwd)")
lineage_config_load "$REPO_ROOT"

PROJECT_KEY=$(onlooker_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"
# Match the spelling the ledger stores. The lookup is an exact string compare,
# and the hook resolves every path it records, so a symlinked checkout would
# otherwise find nothing (ecosystem-htl).
FILE=$(lineage_resolve_path "$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")
  # How much of the change this record's content actually covers. Carried in
  # the header because a list of changes is scanned, not read.
  scope=$(lineage_scope_kind "$(jq -r '.content_scope // ""' <<<"$rec")" "$tool")
  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}) · scope ${scope} · 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"
# Match the spelling the ledger stores. The lookup is an exact string compare,
# and the hook resolves every path it records, so a symlinked checkout would
# otherwise find nothing (ecosystem-htl).
FILE=$(lineage_resolve_path "$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")
  scope_raw=$(jq -r '.content_scope // ""' <<<"$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 $(lineage_tool_phrase "$tool") in session ${sid}${turn:+ (turn ${turn})}."
  # Always printed. A single-line answer is the one most likely to be quoted
  # back as fact, so it is the one that most needs to say what it is worth.
  echo ""

From onlooker-community/ecosystem, MIT.

More from onlooker-community/ecosystem