Trace File Lineage

Trace File Lineage

Keep all analysis local and non-destructive. Never execute scanned project code, follow external symlinks, expose secret contents, or move source files.

Choose a workflow

Use retrospective forensics when the artifact predates capture. Infer candidates, cite evidence, retain alternatives, and state uncertainty.

Use prospective capture before a future file-producing command or agent task. A manual or hook boundary proves only observed co-change. The run wrapper may verify that its child command changed an artifact version; it still does not name an internal writer function.

Set LINEAGE to <skill-dir>/scripts/lineage.py in the POSIX examples below. An installed package instead provides the lineage command (and the equivalent python -m lineage_core), which is preferable when available; in PowerShell use py -3 $Lineage .... Do not assume Bash or a POSIX separator. Build filesystem paths with pathlib, pass child arguments as arrays, and never request shell interpolation.

Query commands default to Markdown and accept --format json when you need to parse the result. doctor also defaults to a readable report; use doctor --format json for the complete machine-readable capability ledger.

Two modes

Manual: answer a question about an existing project. Most answers about files created before any capture existed are candidate, not verified; say so.

Continuous: the user ran lineage enable, which wrote a required instruction into this project's CLAUDE.md and AGENTS.md. When that block is present you must record a boundary at the end of every task that changed files, and you must place new files according to the existing layout. Check with lineage status.

Before creating files in an unfamiliar project, read the conventions first:

python3 "$LINEAGE" layout --root .