100+ AI Agents, Agent Skills and RAG Apps - Free and Open Source.
Add commit-archaeologist skill: reconstruct the why behind code from git history (#974)
Matt Van Horn76b63f64f044
diff --git a/README.md b/README.mdindex 32bfdae8..b819022c 100644--- a/README.md+++ b/README.md@@ -85,6 +85,7 @@ streamlit run travel_agent.py* [⚰️ Project Graveyard](agent_skills/project-graveyard/) - Finds every side project you abandoned, tells you why each one died, and helps you finish the one worth going back to* [🔭 Scope Creep Detector](agent_skills/scope-creep-detector/) - Checks whether a diff grew beyond its stated intent and recommends what to keep, split, or justify+* [🏺 Commit Archaeologist](agent_skills/commit-archaeologist/) - Reconstructs why a file or code region exists from its introducing commit, later edits, co-changes, and intent clues* [🧠 Advisor Orchestrator Worker](agent_skills/advisor-orchestrator-worker/) - Meta Loop with Claude Flabe 5 as advisor, GPT-5.6 as orchestrator, and Gemini 3.5 Flash as worker* [♾️ Self-Improving Agent Skills](agent_skills/self-improving-agent-skills/) - Automatically optimize agent skills using Gemini and ADKdiff --git a/agent_skills/README.md b/agent_skills/README.mdindex 4d45262a..259045c0 100644--- a/agent_skills/README.md+++ b/agent_skills/README.md@@ -19,6 +19,7 @@ Most "skills" on registries are text-only prompt dumps — advice the model alre| Skill | What it does ||---|---|| [🧠 advisor-orchestrator-worker](advisor-orchestrator-worker/) | Turns your agent into the orchestrator of a three-tier model team: cheap stateless workers in parallel, expensive advisor consulted only at commitment boundaries, verification gates between every step — budgeted so a run can't burn a hole in your API bill |+| [🏺 commit-archaeologist](commit-archaeologist/) | Reconstructs why a file or code region exists from local git history, including its introducing commit, later edits, repeated companion files, current authorship, and intent clues || [⚰️ project-graveyard](project-graveyard/) | Scans your machine for dead side projects, autopsies why each one died from its git history (deploy fear, payments wall, killed by a newer project), shows your personal death patterns, and resurrects the one with a pulse — with relapse tracking on every resurrection it prescribes || [🔭 scope-creep-detector](scope-creep-detector/) | Checks a diff against its stated intent, flags unrelated files and scope signals, and recommends what to keep, split, or justify || [♾️ self-improving-agent-skills](self-improving-agent-skills/) | Automatically optimizes agent skills using Gemini and ADK |diff --git a/agent_skills/commit-archaeologist/README.md b/agent_skills/commit-archaeologist/README.mdnew file mode 100644index 00000000..df2e3895--- /dev/null+++ b/agent_skills/commit-archaeologist/README.md@@ -0,0 +1,74 @@+# Commit Archaeologist Agent Skill++`git blame` tells you who last changed a line. Commit Archaeologist reconstructs+why the line exists.++Point it at a tracked file and an optional line range. Its local Python script+finds the introducing commit, orders later modifications, classifies commit+messages, summarizes current authorship, detects repeatedly co-changed files,+and flags issue references, reverts, workarounds, temporary choices, and TODOs.+The agent turns that evidence into a readable history and a change-risk note.++++## Install++```bash+npx skills add https://github.com/Shubhamsaboo/awesome-llm-apps/tree/main/agent_skills/commit-archaeologist+```++The [skills CLI](https://skills.sh) installs the folder for compatible coding+agents. You can also copy this directory into an agent's skills directory.++## Run++Ask your agent:++> Why does `src/cache.py` lines 40-72 exist, and what should I know before I+> change it?++Or run the deterministic core from a clone of this repository:++```bash+python3 agent_skills/commit-archaeologist/scripts/archaeologist.py \+ /path/to/repo src/cache.py --lines 40-72 --json+```++Omit `--lines` to follow the entire file history. Omit `--json` for a compact+terminal summary.++## Output++The JSON dig report contains:++- the normalized region, historical path aliases, and co-change threshold+- the introducing commit+- an oldest-to-newest timeline with changed files and intent categories+- repeated co-changes and their supporting commits+- current blamed-line counts alongside historical commit counts+- intent signals grounded in commit subjects and bodies++Everything runs locally with Python's standard library and git. The script is+read-only and makes no network calls.++## Verify++```bash+python3 agent_skills/evals/commit-archaeologist/test_archaeologist.py+```++The eval builds its own temporary repository and checks ordering, co-changes,+authorship, intent signals, deterministic JSON, and validation errors.++## Files++```text+commit-archaeologist/+|-- SKILL.md+|-- README.md+|-- scripts/archaeologist.py+`-- references/reading-git-history.md+```++Part of [awesome-llm-apps](https://github.com/Shubhamsaboo/awesome-llm-apps).+Apache-2.0. Last verified: July 2026.diff --git a/agent_skills/commit-archaeologist/SKILL.md b/agent_skills/commit-archaeologist/SKILL.mdnew file mode 100644index 00000000..a80214be--- /dev/null+++ b/agent_skills/commit-archaeologist/SKILL.md@@ -0,0 +1,132 @@+---+name: commit-archaeologist+description: >-+ Reconstructs why code exists from local git history, including the introducing+ commit, later changes, current authors, repeated companion files, and likely+ intent. Use when the user asks "why does this code exist", "who wrote this+ function and why", or to "explain the history of this function" before a+ rewrite, refactor, or risky edit. Runs entirely locally.+license: Apache-2.0+metadata:+ author: "Matt Van Horn"+ version: "1.0.0"+ source: "https://github.com/Shubhamsaboo/awesome-llm-apps"+---++# Commit Archaeologist++`git blame` names the last person to touch a line. This skill reconstructs the+reason the line exists. It traces a file or current line range through local git+history, identifies its origin and later edits, finds files that repeatedly+changed beside it, and extracts intent clues from commit messages.++Everything runs locally. No network calls, API keys, or repository writes.++## When to use++- The user asks why a block, function, or file exists+- The user wants to know who introduced code and what changed afterward+- A rewrite or refactor needs historical constraints and change risks+- A workaround, temporary branch, or surprising design choice needs context++## When not to use++- The user only wants raw blame output or a commit list+- The task is to squash, delete, or rewrite git history+- The repository is remote and has not been cloned locally+- The question is about project-wide architecture rather than one file or region++## Gather the target++Get the repository path and tracked file path. Use a line range when the user+names a current block or function. If either path is missing, ask only for the+missing value. Do not scan sibling repositories.++Paths should be relative to the repository and use forward slashes. Line ranges+use inclusive current line numbers such as `40-72`.++## Run the dig++From this skill directory:++```bash+python3 scripts/archaeologist.py /path/to/repo src/cache.py --lines 40-72 --json+```++For the complete history of a file, omit `--lines`:++```bash+python3 scripts/archaeologist.py /path/to/repo src/cache.py --json+```++The script is read-only. With a range it uses git line-log; without one it uses+file history with rename following. It also reads current authorship with blame.+If it rejects a path or range, report that error and ask for a corrected target.++Before interpreting the JSON, read+`references/reading-git-history.md`. Its confidence rules prevent blame+ownership, correlation, and commit-message hints from becoming false certainty.++## Read the JSON++- `region`: normalized repository, current and historical paths, mode, range,+ and co-change threshold+- `introduced_by`: oldest commit in the selected history+- `timeline`: commits ordered oldest to newest, with category, changed files,+ and detected renames+- `co_changed`: files present beside the target in enough selected commits+- `authors`: current blamed lines and historical commit counts, kept separate+- `intent_signals`: issue references, reverts, workarounds, temporary markers,+ and unfinished-work markers found in commit messages++An empty signal list means the messages do not say why. It does not mean the+change had no reason.++## Write the report++Turn the JSON into a short "why this code exists" report:++1. **Bottom line.** One or two sentences with the most likely explanation and+ a confidence label: high, medium, or low.+2. **Origin.** Introducing hash, date, author, subject, and the neighboring+ files that make the initial purpose clearer.+3. **Timeline.** Oldest to newest. Group mechanical edits when they do not+ change the story, but preserve reverts, fixes, and workarounds.+4. **Companion files.** Explain repeated co-changes as a coupling clue. Do not+ treat a one-off file in `changed_files` as a dependency.+5. **Intent evidence.** Quote short commit subjects or signal words. Label any+ conclusion beyond those facts as an inference.+6. **Change risk.** Name the constraints, companion files, and unresolved+ temporary choices worth checking before an edit.++Keep hashes short in prose, but preserve enough characters to identify them.+Do not dump the full JSON unless the user asks.++## Evidence rules++- Current blame ownership is not proof of original authorship.+- The oldest selected commit is the region's introduction, not always the+ file's first commit.+- Repeated co-change suggests coupling; it does not prove a dependency.+- Commit categories are message heuristics, not verified issue types.+- "Temporary" and "workaround" are strong intent clues, but only the message+ author or linked discussion can confirm whether the constraint still applies.+- If the history is thin or messages are vague, say "the history shows" and+ "likely" instead of inventing a design rationale.++## Follow-ups++End by offering one relevant follow-up, such as:++- "Want me to assess whether this looks deliberate or accidental?"+- "Want me to map what could break if this region changes?"++For a deliberate-choice question, weigh repeated edits, issue references,+reverts, and explicit constraint words. For a change-risk question, inspect the+repeated co-change files and the last behavior-changing commits before proposing+edits. Do not modify code until the user asks.++## Files++- `scripts/archaeologist.py`: offline git history walker and JSON report builder+- `references/reading-git-history.md`: interpretation and confidence guidediff --git a/agent_skills/commit-archaeologist/references/reading-git-history.md b/agent_skills/commit-archaeologist/references/reading-git-history.mdnew file mode 100644index 00000000..22b11cea--- /dev/null+++ b/agent_skills/commit-archaeologist/references/reading-git-history.md@@ -0,0 +1,82 @@+# Reading git history without inventing intent++The dig report separates facts from signals. Use this guide before turning it+into a narrative.++## File history and line history answer different questions++File mode uses `git log --follow` and asks how the tracked file evolved. Line+mode uses git line-log and asks which commits shaped the current selected lines.+A line-mode timeline can start long after the file was created. Call its oldest+entry the region's introducing commit, not automatically the file's creator.++Line-log follows patches backward. Large rewrites, copied code, and some renames+can break the chain. When an origin looks too recent, compare it with file mode+and say that the earlier ancestry is uncertain.++## Authorship has two meanings++The `authors` list holds both current blamed-line counts and commit counts in the+selected timeline. Current blame answers who last shaped surviving lines.+Timeline authorship answers who committed the historical changes. Neither fact+alone proves who designed the behavior.++Use precise language:++- Strong: "Ada introduced the selected lines in `a1b2c3d`."+- Strong: "Seven current lines are blamed to Ada."+- Weak: "Ada designed the system this way." This needs message or issue evidence.++## Timeline categories are routing hints++The script labels messages as `feat`, `fix`, `refactor`, `revert`, `hotfix`,+`merge`, or `other`. These labels make the narrative easier to scan. They are+keyword classifications, not proof that a refactor preserved behavior or that a+commit labeled fix solved the root cause.++Read subject, body, and changed files together. A refactor followed by a revert+is more informative than either label alone.++## Co-change is correlation++`co_changed` includes files that crossed a threshold within the selected+timeline. Repetition is useful because a helper changed beside the target in+several commits for a reason more often than by accident.++Treat it as a clue:++- Repeated test co-changes can reveal the behavior the code protects.+- Repeated schema or migration co-changes can reveal a data constraint.+- Repeated configuration co-changes can reveal a deployment constraint.+- Generated or formatting commits can create meaningless co-change patterns.++Say "often changed with" until the code confirms a dependency.++## Intent signals and confidence++Issue or PR references point to likely external context. Revert, workaround,+temporary, and TODO words are direct evidence that the commit author framed the+change that way. They still do not say whether the condition remains true.++Use these confidence levels:++- **High:** explicit constraint language plus repeated supporting changes, or a+ revert that clearly names the behavior being restored.+- **Medium:** message category, changed files, and timeline shape agree, but no+ message states the rationale directly.+- **Low:** sparse history, generic subjects, bulk rewrites, or conflicting clues.++Keep quotes short and traceable to the commit. When the evidence only shows what+changed, report what changed and leave the why open.++## Change-risk checklist++Before recommending an edit, check:++1. Did a prior commit try the same change and get reverted?+2. Do tests, schemas, migrations, or configs repeatedly move with the region?+3. Does a workaround or temporary marker name an external constraint?+4. Does current blame hide an older introducing author after a mechanical edit?+5. Does file mode show ancestry that line mode could not retain?++The safest report names the evidence, the inference, and what would confirm it.diff --git a/agent_skills/commit-archaeologist/scripts/archaeologist.py b/agent_skills/commit-archaeologist/scripts/archaeologist.pynew file mode 100644index 00000000..79eb9506--- /dev/null+++ b/agent_skills/commit-archaeologist/scripts/archaeologist.py@@ -0,0 +1,382 @@+#!/usr/bin/env python3+"""Reconstruct why a file or line range exists from local git history.++Usage:+ python3 archaeologist.py REPO FILE [--lines A-B] [--json]++Python 3.8+, stdlib only. Read-only and offline.+"""++import argparse+import json+import os+import re+import subprocess+import sys+from collections import Counter, defaultdict+++LINE_RANGE_RE = re.compile(r"^([1-9][0-9]*)-([1-9][0-9]*)$")+ISSUE_RE = re.compile(r"(?<![\w/])(?:#[0-9]+|(?:pr|issue|gh)[\s:#-]*[0-9]+)", re.I)+INTENT_PATTERNS = (+ ("revert", re.compile(r"\brevert(?:ed|s|ing)?\b", re.I)),+ ("workaround", re.compile(r"\bwork[ -]?around\b", re.I)),+ ("temporary", re.compile(r"\b(?:temporary|temporarily|temp)\b", re.I)),+ ("todo", re.compile(r"\bTODO\b", re.I)),+)+++class ArchaeologistError(Exception):+ """A user-facing validation or git error."""+++def git(repo, args, required=True):+ """Run a read-only git command and return stdout."""+ try:+ result = subprocess.run(+ ["git", "-C", repo, *args],+ capture_output=True,+ text=True,+ timeout=30,+ )+ except FileNotFoundError as exc:+ raise ArchaeologistError("git is not installed or is not on PATH") from exc+ except subprocess.TimeoutExpired as exc:+ raise ArchaeologistError("git command timed out") from exc+ if result.returncode != 0 and required:+ detail = result.stderr.strip() or result.stdout.strip() or "git command failed"+ raise ArchaeologistError(detail)+ return result.stdout if result.returncode == 0 else ""+++def normalize_inputs(repo_arg, file_arg):+ repo_hint = os.path.abspath(os.path.expanduser(repo_arg))+ if not os.path.isdir(repo_hint):+ raise ArchaeologistError("repository path is not a directory: %s" % repo_arg)+ root = git(repo_hint, ["rev-parse", "--show-toplevel"]).strip()+ if not root:+ raise ArchaeologistError("not a git repository: %s" % repo_arg)+ root = os.path.abspath(root)++ if os.path.isabs(file_arg):+ candidate = os.path.abspath(os.path.expanduser(file_arg))+ else:+ candidate = os.path.abspath(os.path.join(root, file_arg))+ try:+ inside = os.path.commonpath([root, candidate]) == root+ except ValueError:+ inside = False+ if not inside:+ raise ArchaeologistError("file must be inside the repository")++ relative = os.path.relpath(candidate, root).replace(os.sep, "/")+ tracked = git(root, ["ls-files", "--error-unmatch", "--", relative], required=False)+ if not tracked.strip():+ raise ArchaeologistError("file is not tracked at HEAD: %s" % relative)+ return root, relative+++def parse_line_range(value):+ if value is None:+ return None+ match = LINE_RANGE_RE.match(value)+ if not match:+ raise ArchaeologistError("line range must use positive A-B form, such as 40-72")+ start, end = int(match.group(1)), int(match.group(2))+ if start > end:+ raise ArchaeologistError("line range start must not exceed its end")+ return start, end+++def validate_range(repo, path, line_range):+ if line_range is None:+ return+ content = git(repo, ["show", "HEAD:%s" % path])+ line_count = len(content.splitlines())+ if line_range[1] > line_count:+ raise ArchaeologistError(+ "line range ends at %d, but %s has %d lines at HEAD"+ % (line_range[1], path, line_count)+ )+++def history_hashes(repo, path, line_range):+ if line_range:+ selector = "%d,%d:%s" % (line_range[0], line_range[1], path)+ output = git(repo, ["log", "--format=%H", "--no-patch", "-L", selector])+ else:+ output = git(+ repo,+ ["log", "--format=%H", "--no-patch", "--follow", "--", path],+ )+ newest_first = [line.strip() for line in output.splitlines() if line.strip()]+ hashes = []+ seen = set()+ for commit_hash in reversed(newest_first):+ if commit_hash not in seen:+ seen.add(commit_hash)+ hashes.append(commit_hash)+ if not hashes:+ raise ArchaeologistError("no commits found for %s" % path)+ return hashes+++def classify_message(subject, body):+ text = "%s\n%s" % (subject, body)+ lowered = text.lower()+ if subject.lower().startswith("merge "):+ return "merge"+ if re.search(r"\brevert(?:ed|s|ing)?\b", lowered):+ return "revert"+ if re.search(r"\bhot[ -]?fix\b", lowered):+ return "hotfix"+ if re.search(r"\b(refactor|cleanup|restructure|rename)\b", lowered):+ return "refactor"+ if re.search(r"\b(fix|fixed|fixes|bug|patch)\b", lowered):+ return "fix"+ if re.search(r"\b(feat|feature|add|added|introduce|implement)\b", lowered):+ return "feat"+ return "other"+++def changed_file_details(repo, commit_hash):+ output = git(+ repo,+ [+ "diff-tree", "--root", "--no-commit-id", "--name-status", "-r",+ "-M", commit_hash, "--",+ ],+ )+ paths = set()+ renames = []+ for line in output.splitlines():+ fields = line.split("\t")+ if len(fields) >= 3 and fields[0].startswith("R"):+ old_path, new_path = fields[1], fields[2]+ paths.update((old_path, new_path))+ renames.append({"from": old_path, "to": new_path})+ elif len(fields) >= 2:+ paths.add(fields[-1])+ return sorted(paths), renames+++def intent_signals(commit_hash, subject, body):+ text = "%s\n%s" % (subject, body)+ signals = []+ for match in ISSUE_RE.finditer(text):+ signals.append({+ "type": "issue_reference",+ "commit": commit_hash,+ "evidence": match.group(0),+ "subject": subject,+ })+ for signal_type, pattern in INTENT_PATTERNS:+ match = pattern.search(text)+ if match:+ signals.append({+ "type": signal_type,+ "commit": commit_hash,+ "evidence": match.group(0),+ "subject": subject,+ })+ return signals+++def read_commit(repo, commit_hash):+ fmt = "%H%x00%an%x00%ae%x00%aI%x00%s%x00%b"+ raw = git(repo, ["show", "-s", "--format=%s" % fmt, commit_hash]).rstrip("\n")+ parts = raw.split("\x00", 5)+ if len(parts) != 6:+ raise ArchaeologistError("could not parse commit metadata for %s" % commit_hash)+ full_hash, author, email, date, subject, body = parts+ signals = intent_signals(full_hash, subject, body)+ files, renames = changed_file_details(repo, full_hash)+ return {+ "hash": full_hash,+ "short_hash": full_hash[:12],+ "author": author,+ "email": email,+ "date": date,+ "subject": subject,+ "body": body.strip(),+ "category": classify_message(subject, body),+ "changed_files": files,+ "renames": renames,+ "intent_signals": [signal["type"] for signal in signals],+ }, signals+++def blame_authors(repo, path, line_range):+ args = ["blame", "--line-porcelain"]+ if line_range:+ args.extend(["-L", "%d,%d" % line_range])+ args.extend(["HEAD", "--", path])+ output = git(repo, args, required=False)+ counts = Counter()+ names = {}+ current_name = ""+ current_email = ""+ for line in output.splitlines():+ if line.startswith("author "):+ current_name = line[7:]+ elif line.startswith("author-mail "):+ current_email = line[12:].strip("<>")+ elif line.startswith("\t"):+ if current_email:+ key = current_email.lower()+ counts[key] += 1+ names[key] = (current_name, current_email)+ current_name = ""+ current_email = ""+ return counts, names+++def summarize_authors(repo, path, line_range, timeline):+ line_counts, names = blame_authors(repo, path, line_range)+ commit_counts = Counter()+ for entry in timeline:+ key = entry["email"].lower()+ commit_counts[key] += 1+ names.setdefault(key, (entry["author"], entry["email"]))+ authors = []+ for key in set(line_counts) | set(commit_counts):+ name, email = names[key]+ authors.append({+ "name": name,+ "email": email,+ "current_lines": line_counts[key],+ "timeline_commits": commit_counts[key],+ })+ return sorted(+ authors,+ key=lambda author: (+ -author["current_lines"], -author["timeline_commits"],+ author["name"].lower(), author["email"].lower(),+ ),+ )+++def historical_paths(path, timeline):+ aliases = {path}+ for entry in reversed(timeline):+ for rename in entry["renames"]:+ if rename["to"] in aliases:+ aliases.add(rename["from"])+ return aliases+++def summarize_co_changes(path, timeline):+ threshold = max(2, (len(timeline) + 2) // 3)+ aliases = historical_paths(path, timeline)+ commits_by_file = defaultdict(list)+ for entry in timeline:+ for changed in entry["changed_files"]:+ if changed not in aliases:+ commits_by_file[changed].append(entry["hash"])+ co_changed = []+ for changed, commits in commits_by_file.items():+ if len(commits) >= threshold:+ co_changed.append({+ "file": changed,+ "count": len(commits),+ "commit_ratio": round(len(commits) / len(timeline), 3),+ "commits": commits,+ })+ return (+ threshold,+ sorted(co_changed, key=lambda item: (-item["count"], item["file"])),+ sorted(aliases),+ )+++def build_report(repo, path, line_range):+ hashes = history_hashes(repo, path, line_range)+ timeline = []+ signals = []+ for commit_hash in hashes:+ entry, commit_signals = read_commit(repo, commit_hash)+ timeline.append(entry)+ signals.extend(commit_signals)+ threshold, co_changed, aliases = summarize_co_changes(path, timeline)+ return {+ "region": {+ "repo": repo,+ "file": path,+ "mode": "lines" if line_range else "file",+ "lines": (+ {"start": line_range[0], "end": line_range[1]}+ if line_range else None+ ),+ "co_change_threshold": threshold,+ "historical_paths": aliases,+ },+ "introduced_by": timeline[0],+ "timeline": timeline,+ "co_changed": co_changed,+ "authors": summarize_authors(repo, path, line_range, timeline),+ "intent_signals": signals,+ }+++def print_human(report):+ region = report["region"]+ target = region["file"]+ if region["lines"]:+ target += ":%d-%d" % (+ region["lines"]["start"], region["lines"]["end"],+ )+ intro = report["introduced_by"]+ print("COMMIT ARCHAEOLOGIST: %s" % target)+ print("Introduced by %s %s: %s" % (+ intro["short_hash"], intro["author"], intro["subject"],+ ))+ print("\nTIMELINE")+ for entry in report["timeline"]:+ print(" %s %-8s %s" % (+ entry["short_hash"], entry["category"], entry["subject"],+ ))+ print("\nREPEATED CO-CHANGES")+ if report["co_changed"]:+ for item in report["co_changed"]:+ print(" %dx %s" % (item["count"], item["file"]))+ else:+ print(" none above threshold")+ print("\nINTENT SIGNALS")+ if report["intent_signals"]:+ for signal in report["intent_signals"]:+ print(" %s %s %s" % (+ signal["commit"][:12], signal["type"], signal["evidence"],+ ))+ else:+ print(" none found in commit messages")+++def main(argv=None):+ parser = argparse.ArgumentParser(+ description="Explain why a file or line range exists from local git history.",+ )+ parser.add_argument("repo", help="path to a local git repository")+ parser.add_argument("file", help="tracked file path, relative to the repository")+ parser.add_argument("--lines", metavar="A-B", help="current line range to trace")+ parser.add_argument("--json", action="store_true", dest="as_json",+ help="emit the structured dig report as JSON")+ args = parser.parse_args(argv)++ try:+ repo, path = normalize_inputs(args.repo, args.file)+ line_range = parse_line_range(args.lines)+ validate_range(repo, path, line_range)+ report = build_report(repo, path, line_range)+ except ArchaeologistError as exc:+ print("error: %s" % exc, file=sys.stderr)+ return 2++ if args.as_json:+ print(json.dumps(report, indent=2, sort_keys=True))+ else:+ print_human(report)+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/agent_skills/evals/commit-archaeologist/evals.json b/agent_skills/evals/commit-archaeologist/evals.jsonnew file mode 100644index 00000000..17b0ea9c--- /dev/null+++ b/agent_skills/evals/commit-archaeologist/evals.json@@ -0,0 +1,38 @@+{+ "skill_name": "commit-archaeologist",+ "evals": [+ {+ "id": 1,+ "prompt": "Why does src/cache.py lines 40-72 exist? Trace who introduced it and what changed later.",+ "expected_output": "A history report grounded in the local repository, with the introducing commit, chronological timeline, repeated co-changes, and intent evidence.",+ "expectations": [+ "The agent runs scripts/archaeologist.py with the user-provided repository, file, line range, and --json",+ "The report names the introducing commit and presents later modifications from oldest to newest",+ "Repeatedly co-changed files are separated from one-off neighboring changes",+ "Intent claims cite commit messages or explicit signals and label inference as inference",+ "The agent offers to assess whether the choice was deliberate or what could break if the region changes"+ ]+ },+ {+ "id": 2,+ "prompt": "Who wrote this function and why? The repo is /work/api and the file is src/retry.py.",+ "expected_output": "A file-wide dig report that distinguishes current blame ownership from historical commit authorship and explains the likely reason for the function.",+ "expectations": [+ "The agent uses only the specified local repository and file",+ "Current blame ownership and timeline authors are not treated as the same fact",+ "The narrative includes timeline, co-change, and intent sections",+ "The answer does not claim certainty when the commit evidence is ambiguous"+ ]+ },+ {+ "id": 3,+ "prompt": "Explain the history of this function before I rewrite it.",+ "expected_output": "The agent asks only for the missing repository, file, or line range, then produces a change-risk oriented history report.",+ "expectations": [+ "The agent requests missing path information instead of scanning unrelated repositories",+ "The report identifies repeated companion files and temporary or workaround signals",+ "The closing follow-up focuses on deliberate constraints and change risks"+ ]+ }+ ]+}diff --git a/agent_skills/evals/commit-archaeologist/test_archaeologist.py b/agent_skills/evals/commit-archaeologist/test_archaeologist.pynew file mode 100644index 00000000..610c0008--- /dev/null+++ b/agent_skills/evals/commit-archaeologist/test_archaeologist.py@@ -0,0 +1,247 @@+#!/usr/bin/env python3+"""Deterministic eval for the commit-archaeologist skill.++Builds a temporary git repository with a known file history, runs the skill's+offline script, and checks the resulting dig report.++ python3 agent_skills/evals/commit-archaeologist/test_archaeologist.py++Python stdlib plus git only. The fixture never touches the source checkout.+"""++import json+import os+import shutil+import subprocess+import sys+import tempfile+++SCRIPT = os.path.abspath(os.path.join(+ os.path.dirname(__file__),+ "..", "..", "commit-archaeologist", "scripts", "archaeologist.py",+))+EMAIL = "[email protected]"+checks = []+++def check(name, condition, detail=""):+ checks.append(bool(condition))+ status = "PASS" if condition else "FAIL"+ suffix = " - %s" % detail if detail and not condition else ""+ print(" %s %s%s" % (status, name, suffix))+++def git(repo, *args, env=None):+ result = subprocess.run(+ ["git", *args], cwd=repo, env=env, capture_output=True, text=True,+ )+ if result.returncode != 0:+ raise RuntimeError(result.stderr.strip() or "git command failed")+ return result.stdout.strip()+++def write(repo, path, content):+ target = os.path.join(repo, path)+ os.makedirs(os.path.dirname(target), exist_ok=True)+ with open(target, "w", encoding="utf-8") as handle:+ handle.write(content)+++def commit(repo, date, message, files):+ for path, content in files.items():+ write(repo, path, content)+ git(repo, "add", "-A")+ env = dict(+ os.environ,+ GIT_AUTHOR_DATE=date,+ GIT_COMMITTER_DATE=date,+ )+ git(repo, "commit", "-m", message, env=env)+ return git(repo, "rev-parse", "HEAD")+++def build_repo(root):+ repo = os.path.join(root, "fixture")+ os.makedirs(repo)+ git(repo, "init", "-q")+ git(repo, "config", "user.name", "Ada Archaeologist")+ git(repo, "config", "user.email", EMAIL)++ introduced = commit(+ repo,+ "2026-01-01T10:00:00+0000",+ "feat: introduce calculator #12",+ {+ "src/calculator.py": (+ "def add(values):\n"+ " return sum(values)\n"+ ),+ "docs/decision.md": "Calculator experiment notes.\n",+ },+ )+ refactored = commit(+ repo,+ "2026-01-02T10:00:00+0000",+ "refactor: name the accumulator",+ {+ "src/calculator.py": (+ "def add(values):\n"+ " total = 0\n"+ " for value in values:\n"+ " total += value\n"+ " return total\n"+ ),+ "src/helpers.py": (+ "def normalize_zero():\n"+ " return 0\n"+ ),+ },+ )+ workaround = commit(+ repo,+ "2026-01-03T10:00:00+0000",+ "fix: temporary workaround for empty totals #34",+ {+ "src/calculator.py": (+ "from .helpers import normalize_zero\n\n"+ "def add(values):\n"+ " total = 0\n"+ " for value in values:\n"+ " total += value\n"+ " return total if values else normalize_zero()\n"+ ),+ "src/helpers.py": (+ "def normalize_zero():\n"+ " # Keep the legacy integer return type.\n"+ " return 0\n"+ ),+ },+ )+ return repo, [introduced, refactored, workaround]+++def run(repo, *args, file_path="src/calculator.py"):+ return subprocess.run(+ [sys.executable, SCRIPT, repo, file_path, *args],+ capture_output=True,+ text=True,+ )+++def main():+ root = tempfile.mkdtemp(prefix="commit-archaeologist-eval-")+ try:+ repo, expected_hashes = build_repo(root)++ print("line-range report:")+ result = run(repo, "--lines", "1-7", "--json")+ check("script exits cleanly", result.returncode == 0, result.stderr)+ if result.returncode != 0:+ return 1+ report = json.loads(result.stdout)++ check(+ "region identifies the requested lines",+ report["region"]["file"] == "src/calculator.py"+ and report["region"]["lines"] == {"start": 1, "end": 7},+ str(report.get("region")),+ )+ check(+ "introducing commit is the first commit",+ report["introduced_by"]["hash"] == expected_hashes[0],+ report["introduced_by"]["hash"],+ )+ timeline_hashes = [entry["hash"] for entry in report["timeline"]]+ check(+ "timeline is oldest to newest",+ timeline_hashes == expected_hashes,+ str(timeline_hashes),+ )+ check(+ "commit categories follow message intent",+ [entry["category"] for entry in report["timeline"]]+ == ["feat", "refactor", "fix"],+ )+ co_changed = {entry["file"]: entry for entry in report["co_changed"]}+ check(+ "helper is detected as a repeated co-change",+ co_changed.get("src/helpers.py", {}).get("count") == 2,+ str(report["co_changed"]),+ )+ check(+ "one-off neighboring files stay below the threshold",+ "docs/decision.md" not in co_changed,+ str(report["co_changed"]),+ )+ single_commit = run(repo, "--json", file_path="docs/decision.md")+ single_commit_report = (+ json.loads(single_commit.stdout) if single_commit.returncode == 0 else {}+ )+ check(+ "single-commit history has no repeated co-changes",+ single_commit.returncode == 0+ and single_commit_report.get("co_changed") == []+ and single_commit_report.get("region", {}).get("co_change_threshold") == 2,+ single_commit.stderr or str(single_commit_report),+ )+ signal_types = {entry["type"] for entry in report["intent_signals"]}+ check("workaround signal is present", "workaround" in signal_types)+ check("temporary signal is present", "temporary" in signal_types)+ check("issue reference signal is present", "issue_reference" in signal_types)+ check(+ "blame authorship is summarized",+ any(+ author["email"] == EMAIL and author["current_lines"] == 7+ for author in report["authors"]+ ),+ str(report["authors"]),+ )++ repeat = run(repo, "--lines", "1-7", "--json")+ check("JSON output is deterministic", repeat.stdout == result.stdout)++ print("file-wide rename and error behavior:")+ git(repo, "mv", "src/calculator.py", "src/arithmetic.py")+ git(repo, "commit", "-m", "refactor: rename calculator module")+ renamed = git(repo, "rev-parse", "HEAD")+ file_result = run(repo, "--json", file_path="src/arithmetic.py")+ file_report = json.loads(file_result.stdout) if file_result.returncode == 0 else {}+ check("file-wide mode exits cleanly", file_result.returncode == 0, file_result.stderr)+ check(+ "file-wide mode uses follow history",+ file_report.get("region", {}).get("mode") == "file"+ and [entry["hash"] for entry in file_report.get("timeline", [])]+ == expected_hashes + [renamed],+ )+ check(+ "a target's old name is not reported as a co-change",+ all(+ entry["file"] != "src/calculator.py"+ for entry in file_report.get("co_changed", [])+ ),+ str(file_report.get("co_changed")),+ )++ invalid = run(+ repo, "--lines", "7-1", "--json", file_path="src/arithmetic.py",+ )+ check("invalid line range fails", invalid.returncode != 0)+ check(+ "invalid line range explains the problem without a traceback",+ "line range" in invalid.stderr.lower() and "traceback" not in invalid.stderr.lower(),+ invalid.stderr,+ )++ print()+ if all(checks):+ print("PASS - %d/%d checks" % (len(checks), len(checks)))+ return 0+ print("FAIL - %d/%d checks passed" % (sum(checks), len(checks)))+ return 1+ finally:+ shutil.rmtree(root, ignore_errors=True)+++if __name__ == "__main__":+ sys.exit(main())diff --git a/agent_skills/evals/commit-archaeologist/trigger-cases.json b/agent_skills/evals/commit-archaeologist/trigger-cases.jsonnew file mode 100644index 00000000..2efc3039--- /dev/null+++ b/agent_skills/evals/commit-archaeologist/trigger-cases.json@@ -0,0 +1,42 @@+{+ "skill": "commit-archaeologist",+ "purpose": "Trigger behavior spec. CI checks that positive prompts match the skill description more strongly than near-misses.",+ "cases": [+ {+ "id": "why-code-exists",+ "prompt": "why does this code exist",+ "should_trigger": true,+ "assert": "Traces the relevant lines through local git history and explains the evidence for their likely intent."+ },+ {+ "id": "who-wrote-function",+ "prompt": "who wrote this function and why",+ "should_trigger": true,+ "assert": "Reports current authorship, the introducing commit, later changes, and likely intent."+ },+ {+ "id": "explain-function-history",+ "prompt": "explain the history of this function",+ "should_trigger": true,+ "assert": "Builds a chronological narrative for the function from local git evidence."+ },+ {+ "id": "near-miss-git-blame",+ "prompt": "run git blame on src/parser.py",+ "should_trigger": false,+ "assert": "Does not trigger for a direct request to print blame output without intent analysis."+ },+ {+ "id": "near-miss-delete-history",+ "prompt": "delete this file's history",+ "should_trigger": false,+ "assert": "Does not trigger for destructive history rewriting."+ },+ {+ "id": "near-miss-squash",+ "prompt": "squash my commits",+ "should_trigger": false,+ "assert": "Does not trigger for commit rewriting."+ }+ ]+}