半年前にエージェントが書いた行の意図を追えるようにする — コミット粒度と来歴トレーラの設計

# .agent/freeze_provenance.py
"""計画ステップの検証記録から、後から読む価値のある要旨だけを抜き出して凍結する。
 
スクリーンショットや全文ログは保存しない。半年後に必要なのは
「何を確かめたか」「何が根拠だったか」であって、画素ではないため。
"""
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:
    """1 ステップ分の来歴を JSON として保存し、そのパスを返す。"""
    PROVENANCE_DIR.mkdir(exist_ok=True)
 
    payload = {
        "run_id": run_id,
        "step_id": step_id,
        "model": record["model"],
        # なぜこう実装したか（人間が読む本文）
        "intent": record["intent"][:MAX_NOTE_CHARS],
        # 何をもって正しいと判断したか（検証の要旨のみ）
        "verification": [v[:240] for v in record.get("verification", [])][:6],
        # 検討して捨てた選択肢。これが半年後に一番効く
        "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")
 
    # 凍結ファイル自体を同じコミットに含める
    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 — 使い方: why.py <file> <line>
"""指定行を書いたコミットの来歴を辿り、意図・検証・棄却案を表示する。"""
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> で該当行だけを blame し、先頭のコミット SHA を得る
    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("  → 人間が直接書いた行です（来歴トレーラなし）。")
        return 0
 
    print(f"  model: {trailer(sha, 'Agent-Model')}  run: {run_id}  step: {step_id}")
 
    # 凍結済みの来歴を探す。ファイル名は run-step-digest 形式
    matches = sorted(pathlib.Path(".agent-provenance").glob(f"{run_id}-{step_id}-*.json"))
    if not matches:
        print("  → 来歴ファイルが見つかりません（凍結前のコミットの可能性）。")
        return 1
 
    rec = json.loads(matches[-1].read_text(encoding="utf-8"))
    print(f"\n  意図: {rec['intent']}")
    if rec["verification"]:
        print("  検証:")
        for v in rec["verification"]:
            print(f"    - {v}")
    if rec["rejected"]:
        print("  棄却した案:")
        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"
 
# エージェント実行中でなければ何も要求しない（手作業のコミットは自由）
[ "${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 "❌ トレーラ ${KEY} がありません。commit-step.sh 経由でコミットしてください。" >&2
    exit 1
  fi
done
 
# 来歴ファイルの同梱を確認する
if ! git diff --cached --name-only | grep -q '^\.agent-provenance/'; then
  echo "❌ .agent-provenance/ の凍結ファイルが同梱されていません。" >&2
  exit 1
fi