Tracing Why an Agent Wrote That Line Six Months Ago — Commit Granularity and Provenance Trailers

# .agent/freeze_provenance.py
"""Extract, from a plan step's verification record, only what is worth reading later.
 
Screenshots and full logs are deliberately not kept. What you need six months
from now is what was checked and what it rested on -- not pixels.
"""
from __future__ import annotations
 
import hashlib
import json
import pathlib
import subprocess
import sys
 
PROVENANCE_DIR = pathlib.Path(".agent-provenance")
MAX_NOTE_CHARS = 1200
 
 
def freeze(run_id: str, step_id: str, record: dict) -> pathlib.Path:
    """Persist one step's provenance as JSON and return its path."""
    PROVENANCE_DIR.mkdir(exist_ok=True)
 
    payload = {
        "run_id": run_id,
        "step_id": step_id,
        "model": record["model"],
        # Why it was built this way (prose, for humans).
        "intent": record["intent"][:MAX_NOTE_CHARS],
        # What established correctness (summary only).
        "verification": [v[:240] for v in record.get("verification", [])][:6],
        # Options considered and discarded. This is what pays off later.
        "rejected": [r[:240] for r in record.get("rejected", [])][:4],
        "plan_sha": record["plan_sha"],
    }
 
    body = json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True)
    digest = hashlib.sha256(body.encode("utf-8")).hexdigest()[:12]
    path = PROVENANCE_DIR / f"{run_id}-{step_id}-{digest}.json"
    path.write_text(body + "\n", encoding="utf-8")
 
    # The frozen record ships inside the same commit it describes.
    subprocess.run(["git", "add", str(path)], check=True)
    return path
 
 
if __name__ == "__main__":
    record = json.load(sys.stdin)
    out = freeze(sys.argv[1], sys.argv[2], record)
    print(out)

#!/usr/bin/env python3
# .agent/why.py -- usage: why.py <file> <line>
"""Trace a line to its commit, then to the intent, verification, and rejects behind it."""
from __future__ import annotations
 
import json
import pathlib
import subprocess
import sys
 
 
def _git(*args: str) -> str:
    return subprocess.run(
        ["git", *args], check=True, capture_output=True, text=True
    ).stdout.strip()
 
 
def blame_commit(path: str, line: int) -> str:
    # -L <line>,<line> blames exactly one line; the SHA leads the porcelain output.
    out = _git("blame", "-L", f"{line},{line}", "--porcelain", "--", path)
    return out.split("\n", 1)[0].split(" ", 1)[0]
 
 
def trailer(sha: str, key: str) -> str:
    return _git("log", "-1", f"--format=%(trailers:key={key},valueonly)", sha).strip()
 
 
def main() -> int:
    path, line = sys.argv[1], int(sys.argv[2])
    sha = blame_commit(path, line)
 
    subject = _git("log", "-1", "--format=%s", sha)
    run_id = trailer(sha, "Agent-Run-Id")
    step_id = trailer(sha, "Agent-Step")
 
    print(f"{sha[:12]}  {subject}")
 
    if not run_id:
        print("  -> Written directly by a human (no provenance trailer).")
        return 0
 
    print(f"  model: {trailer(sha, 'Agent-Model')}  run: {run_id}  step: {step_id}")
 
    # Frozen records are named run-step-digest.json
    matches = sorted(pathlib.Path(".agent-provenance").glob(f"{run_id}-{step_id}-*.json"))
    if not matches:
        print("  -> No provenance file found (commit likely predates freezing).")
        return 1
 
    rec = json.loads(matches[-1].read_text(encoding="utf-8"))
    print(f"\n  intent: {rec['intent']}")
    if rec["verification"]:
        print("  verified by:")
        for v in rec["verification"]:
            print(f"    - {v}")
    if rec["rejected"]:
        print("  rejected alternatives:")
        for r in rec["rejected"]:
            print(f"    - {r}")
    return 0
 
 
if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env bash
# .git/hooks/commit-msg
set -euo pipefail
MSG_FILE="$1"
 
# Demand nothing outside agent runs. Manual commits stay unencumbered.
[ "${AGENT_RUN_ID:-}" = "" ] && exit 0
 
for KEY in Agent-Run-Id Agent-Step Agent-Model Agent-Plan-Sha; do
  if ! git interpret-trailers --parse < "${MSG_FILE}" | grep -q "^${KEY}:"; then
    echo "❌ Missing trailer ${KEY}. Commit through commit-step.sh." >&2
    exit 1
  fi
done
 
# The frozen provenance record must ride along.
if ! git diff --cached --name-only | grep -q '^\.agent-provenance/'; then
  echo "❌ No frozen record staged under .agent-provenance/." >&2
  exit 1
fi