gitvow 0.6.0__tar.gz → 0.7.0__tar.gz

{gitvow-0.6.0/src/gitvow.egg-info → gitvow-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.6.0
+Version: 0.7.0
 Summary: Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies.
 Author-email: Nikhil Bora <nikhil@wirevow.com>
 License: Apache-2.0

{gitvow-0.6.0 → gitvow-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitvow"
-version = "0.6.0"
+version = "0.7.0"
 description = "Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{gitvow-0.6.0 → gitvow-0.7.0}/src/gitvow/cli.py

@@ -9,6 +9,7 @@ import re
 import sys
 
 from . import __version__
+from . import recall as rec
 from . import snapshots as snap
 from .collect import collect, summarize_text
 from .hooks import HANDLERS, LEGACY_NOTES_REF, notes_ref
@@ -211,6 +212,26 @@ def cmd_restore(a: argparse.Namespace) -> int:
     return rc
 
 
+def cmd_why(a: argparse.Namespace) -> int:
+    print(rec.why(os.getcwd(), a.path))
+    return 0
+
+
+def cmd_trace(a: argparse.Namespace) -> int:
+    print(rec.trace(os.getcwd(), a.spec))
+    return 0
+
+
+def cmd_recall(a: argparse.Namespace) -> int:
+    print(rec.recall(os.getcwd(), a.words, None, a.limit))
+    return 0
+
+
+def cmd_handoff(a: argparse.Namespace) -> int:
+    print(rec.handoff(os.getcwd(), a.session))
+    return 0
+
+
 def cmd_push_notes(a: argparse.Namespace) -> int:
     import subprocess
 
@@ -304,6 +325,19 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("n", type=int)
     s.add_argument("--to")
     s.set_defaults(f=cmd_restore)
+    s = sub.add_parser("why", help="which sessions shaped a file: commits, plans, attribution")
+    s.add_argument("path")
+    s.set_defaults(f=cmd_why)
+    s = sub.add_parser("trace", help="who wrote these lines: gitvow trace path[:start-end]")
+    s.add_argument("spec")
+    s.set_defaults(f=cmd_trace)
+    s = sub.add_parser("recall", help="sessions whose notes or ledger mention the words")
+    s.add_argument("words", nargs="+")
+    s.add_argument("--limit", type=int, default=10)
+    s.set_defaults(f=cmd_recall)
+    s = sub.add_parser("handoff", help="markdown summary for the next agent")
+    s.add_argument("--session")
+    s.set_defaults(f=cmd_handoff)
     s = sub.add_parser("push-notes", help="push refs/notes/gitvow/* to a remote (default origin)")
     s.add_argument("remote", nargs="?", default="origin")
     s.set_defaults(f=cmd_push_notes)

gitvow-0.7.0/src/gitvow/recall.py

@@ -0,0 +1,285 @@
+"""The record answers the next session: why, trace, recall, handoff. Read-only over trailers, notes, snapshots, ledger."""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import re
+from typing import Any
+
+from .hooks import LEGACY_NOTES_REF, notes_ref
+from .report import STEP_RE, TRAILER_RE
+from .snapshots import list_snapshots
+from .state import git, load_state, toplevel
+
+MAX_PLAN = 200
+
+
+def _note(cwd: str, sha: str, sid: str) -> dict[str, Any] | None:
+    for ref in (notes_ref(sid), LEGACY_NOTES_REF):
+        rc, body, _ = git(["notes", f"--ref={ref}", "show", sha], cwd)
+        if rc == 0 and body.startswith("gitvow-session"):
+            try:
+                return json.loads(body.split("\n", 1)[1])
+            except (json.JSONDecodeError, IndexError):
+                return None
+    return None
+
+
+def _commits(cwd: str, path: str | None = None, limit: int = 200) -> list[dict[str, Any]]:
+    args = ["log", f"-{limit}", "--format=%H%x00%ad%x00%s%x00%B%x01", "--date=short"]
+    if path:
+        args += ["--follow", "--", path]
+    rc, out, _ = git(args, cwd)
+    rows: list[dict[str, Any]] = []
+    if rc != 0:
+        return rows
+    for rec in out.split("\x01"):
+        rec = rec.strip("\n")
+        if not rec.strip():
+            continue
+        sha, date, subject, body = rec.split("\x00", 3)
+        m = TRAILER_RE.search(body)
+        row: dict[str, Any] = {
+            "sha": sha,
+            "short": sha[:7],
+            "date": date,
+            "subject": subject,
+            "kind": "person",
+            "session": None,
+            "step": None,
+            "note": None,
+        }
+        if m:
+            sm = STEP_RE.search(body)
+            row.update(
+                {
+                    "kind": "agent",
+                    "session": m.group(1),
+                    "step": int(sm.group(1)) if sm else None,
+                    "note": _note(cwd, sha, m.group(1)),
+                }
+            )
+        rows.append(row)
+    return rows
+
+
+def _plan(note: dict[str, Any] | None) -> str:
+    p = ((note or {}).get("last_stated_plan") or "").strip().replace("\n", " ")
+    return (p[: MAX_PLAN - 1] + "…") if len(p) > MAX_PLAN else p
+
+
+def why(cwd: str, path: str) -> str:
+    top = toplevel(cwd) or cwd
+    rel = os.path.relpath(os.path.abspath(path), top) if os.path.isabs(path) else path
+    rows = _commits(top, rel)
+    if not rows:
+        return f"{rel}: no commits found"
+    agent = [r for r in rows if r["kind"] == "agent"]
+    sessions = {r["session"] for r in agent}
+    lines = [
+        f"{rel} · {len(agent)} agent commit{'s' if len(agent) != 1 else ''}, {len(rows) - len(agent)} human commit{'s' if len(rows) - len(agent) != 1 else ''}, {len(sessions)} session{'s' if len(sessions) != 1 else ''}",
+        "",
+    ]
+    snaps = {s["ref"] for s in list_snapshots(top) if s.get("file") == rel}
+    for r in rows[:30]:
+        if r["kind"] == "person":
+            lines.append(f"{r['date']}  {r['short']}  (person)  {r['subject'][:70]}")
+            continue
+        att = (r["note"] or {}).get("attribution") or {}
+        share = att.get("agent_share")
+        human = att.get("lines_changed_by_human_after_agent") or 0
+        extra = f"agent share {share:.2f}" if isinstance(share, (int, float)) else "attribution n/a"
+        if human:
+            extra += f" · {human} line{'s' if human != 1 else ''} changed by a person afterwards"
+        step = f"step {r['step']}" if r["step"] is not None else ""
+        lines.append(f"{r['date']}  {r['short']}  session {r['session'][:8]} {step:<8} {extra}")
+        plan = _plan(r["note"])
+        lines.append(
+            f"  {plan}"
+            if plan
+            else "  (no plan stated before committing)"
+            if r["note"]
+            else "  (session note not available; run gitvow push-notes on the author's machine)"
+        )
+    if snaps:
+        lines += [
+            "",
+            f"{len(snaps)} snapshot{'s' if len(snaps) != 1 else ''} of this file from agent edits; see gitvow snapshots",
+        ]
+    return "\n".join(lines)
+
+
+def trace(cwd: str, spec: str) -> str:
+    top = toplevel(cwd) or cwd
+    m = re.match(r"^(.*?)(?::(\d+)(?:-(\d+))?)?$", spec)
+    path = m.group(1) if m else spec
+    rel = os.path.relpath(os.path.abspath(path), top) if os.path.isabs(path) else path
+    args = ["blame", "--line-porcelain"]
+    if m and m.group(2):
+        args += ["-L", f"{m.group(2)},{m.group(3) or m.group(2)}"]
+    rc, out, err = git([*args, "--", rel], top)
+    if rc != 0:
+        return err or f"cannot blame {rel}"
+    shas: list[str] = []
+    line_no = int(m.group(2)) if m and m.group(2) else 1
+    lines_by_sha: dict[str, list[int]] = {}
+    for ln in out.splitlines():
+        if re.match(r"^[0-9a-f]{40} ", ln):
+            sha = ln.split()[0]
+            parts = ln.split()
+            final = int(parts[2]) if len(parts) > 2 else line_no
+            lines_by_sha.setdefault(sha, []).append(final)
+            if sha not in shas:
+                shas.append(sha)
+    info: dict[str, dict[str, Any]] = {}
+    for sha in shas:
+        rc, body, _ = git(["log", "-1", "--format=%B", sha], top)
+        tm = TRAILER_RE.search(body or "")
+        if tm:
+            sm = STEP_RE.search(body)
+            info[sha] = {
+                "kind": "agent",
+                "session": tm.group(1),
+                "step": int(sm.group(1)) if sm else None,
+                "note": _note(top, sha, tm.group(1)),
+            }
+        else:
+            info[sha] = {"kind": "person"}
+    # group consecutive lines per sha
+    out_lines = [f"{rel}" + (f":{m.group(2)}-{m.group(3) or m.group(2)}" if m and m.group(2) else "")]
+    for sha in shas:
+        nums = sorted(lines_by_sha[sha])
+        ranges, start, prev = [], nums[0], nums[0]
+        for n in nums[1:]:
+            if n != prev + 1:
+                ranges.append((start, prev))
+                start = n
+            prev = n
+        ranges.append((start, prev))
+        rtxt = ", ".join(f"{a}-{b}" if a != b else str(a) for a, b in ranges[:6]) + (" …" if len(ranges) > 6 else "")
+        i = info[sha]
+        if i["kind"] == "agent":
+            step = f"step {i['step']}" if i["step"] is not None else ""
+            plan = _plan(i["note"])
+            out_lines.append(
+                f"lines {rtxt:<14} agent   {sha[:7]}  session {i['session'][:8]} {step}"
+                + (f'  "{plan}"' if plan else "")
+            )
+        else:
+            out_lines.append(f"lines {rtxt:<14} person  {sha[:7]}")
+    return "\n".join(out_lines)
+
+
+def recall(cwd: str, words: list[str], home: str | None = None, limit: int = 10) -> str:
+    top = toplevel(cwd) or cwd
+    terms = [w.lower() for w in words if w.strip()]
+    if not terms:
+        return "give one or more words to recall"
+    hits: dict[str, dict[str, Any]] = {}
+    for r in _commits(top, None, 2000):
+        if r["kind"] != "agent":
+            continue
+        hay = " ".join(
+            [
+                r["subject"],
+                _plan(r["note"]),
+                " ".join((r["note"] or {}).get("files_written_by_agent_this_session") or []),
+            ]
+        ).lower()
+        score = sum(1 for t in terms if t in hay)
+        if not score:
+            continue
+        h = hits.setdefault(
+            r["session"],
+            {"session": r["session"], "date": r["date"], "commits": 0, "plan": "", "score": 0, "source": "notes"},
+        )
+        h["commits"] += 1
+        h["score"] = max(h["score"], score)
+        h["plan"] = h["plan"] or _plan(r["note"]) or r["subject"]
+    led = os.path.join(home or os.path.expanduser("~"), ".gitvow", "ledger")
+    for f in glob.glob(os.path.join(led, "*.json")):
+        try:
+            rec = json.load(open(f))  # noqa: SIM115
+        except (OSError, json.JSONDecodeError):
+            continue
+        if os.path.realpath(rec.get("repo") or "") != os.path.realpath(top):
+            continue
+        hay = (
+            " ".join([rec.get("last_stated_plan") or ""] + [t.get("arg", "") for t in rec.get("tool_calls", [])])
+        ).lower()
+        score = sum(1 for t in terms if t in hay)
+        if score and rec.get("session_id") not in hits:
+            hits[rec["session_id"]] = {
+                "session": rec["session_id"],
+                "date": (rec.get("started") or "")[:10],
+                "commits": len(rec.get("commits_during_session") or []),
+                "plan": _plan(rec),
+                "score": score,
+                "source": "ledger",
+            }
+    if not hits:
+        return f"nothing recorded mentions: {' '.join(words)}"
+    rows = sorted(hits.values(), key=lambda h: (-h["score"], h["date"]), reverse=False)[:limit]
+    out = [f"{len(hits)} session{'s' if len(hits) != 1 else ''} mention {' '.join(words)}:"]
+    for h in rows:
+        out.append(
+            f'session {h["session"][:8]}  {h["date"]}  {h["commits"]} commit{"s" if h["commits"] != 1 else ""}  "{h["plan"]}"'
+            + ("  (ledger only)" if h["source"] == "ledger" else "")
+        )
+    return "\n".join(out)
+
+
+def handoff(cwd: str, session_id: str | None = None, home: str | None = None) -> str:
+    top = toplevel(cwd) or cwd
+    st = load_state(top)
+    sid = session_id or st.get("session_id")
+    led_dir = os.path.join(home or os.path.expanduser("~"), ".gitvow", "ledger")
+    rec: dict[str, Any] = {}
+    if sid and os.path.exists(os.path.join(led_dir, f"{sid}.json")):
+        try:
+            rec = json.load(open(os.path.join(led_dir, f"{sid}.json")))  # noqa: SIM115
+        except (OSError, json.JSONDecodeError):
+            rec = {}
+    if not sid:
+        return "no session known in this repository; pass --session <id>"
+    commits = [r for r in _commits(top, None, 500) if r["session"] == sid]
+    files = sorted(
+        {f for r in commits for f in ((r["note"] or {}).get("files_written_by_agent_this_session") or [])}
+        | set(st.get("agent_blobs", {}).keys() if st.get("session_id") == sid else [])
+    )
+    _, dirty, _ = git(["diff", "--shortstat", "HEAD"], top)
+    snaps = list_snapshots(top, sid)
+    plan = _plan(rec) or next((_plan(r["note"]) for r in commits if _plan(r["note"])), "")
+    confirms = []
+    gd_log = os.path.join(top, ".git", "gitvow-hooks.log")
+    if os.path.exists(gd_log):
+        with open(gd_log) as fh:
+            for ln in fh:
+                try:
+                    e = json.loads(ln)
+                except json.JSONDecodeError:
+                    continue
+                if e.get("kind") == "confirm_required" and e.get("session_id") == sid:
+                    confirms.append(f"{e.get('detail', '')[:60]} ({e.get('reason', '')[:60]})")
+    out = [f"# Handoff · session {sid[:8]} · repo {os.path.basename(top)}", ""]
+    out.append(f"Last stated plan: {plan or '(none recorded)'}")
+    out.append(
+        "Commits this session: "
+        + (", ".join(f"{r['short']} {r['subject'][:50]}" for r in commits) if commits else "none")
+    )
+    out.append("Files the agent wrote: " + (", ".join(files[:20]) if files else "none recorded"))
+    out.append(
+        f"Uncommitted now: {dirty.strip() or 'clean'}" + (f" · last snapshot {snaps[-1]['ref']}" if snaps else "")
+    )
+    out.append(
+        f"Open confirmations: {len(confirms)}" + ("".join(f"\n  - {c}" for c in confirms[-5:]) if confirms else "")
+    )
+    if rec.get("tool_calls"):
+        out.append(f"Tool calls in session: {len(rec['tool_calls'])}")
+    out += [
+        "",
+        "Next agent: read `gitvow why <file>` for any file above before changing it; snapshots hold the exact versions this session produced.",
+    ]
+    return "\n".join(out)

{gitvow-0.6.0 → gitvow-0.7.0/src/gitvow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.6.0
+Version: 0.7.0
 Summary: Provenance and policy gate for AI-agent coding sessions: session trailers on commits, redacted session notes in git, a tool-call gate, and a local ledger. No runtime dependencies.
 Author-email: Nikhil Bora <nikhil@wirevow.com>
 License: Apache-2.0

{gitvow-0.6.0 → gitvow-0.7.0}/src/gitvow.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/gitvow/default_policy.json
 src/gitvow/install.py
 src/gitvow/policy.py
 src/gitvow/providers.py
+src/gitvow/recall.py
 src/gitvow/redact.py
 src/gitvow/report.py
 src/gitvow/selftest.py
@@ -30,6 +31,7 @@ tests/test_install_cli.py
 tests/test_packaging.py
 tests/test_policy.py
 tests/test_providers.py
+tests/test_recall.py
 tests/test_redact.py
 tests/test_report.py
 tests/test_snapshots.py

gitvow-0.7.0/tests/test_recall.py

@@ -0,0 +1,107 @@
+import json
+
+from gitvow import cli
+from gitvow.hooks import post_tool_use, pre_tool_use, session_start, stop
+from gitvow.install import _write_git_hook
+from tests.conftest import git
+
+
+def _agent_session(repo, home, payload, sid, file, content, subject, transcript=""):
+    p = payload("SessionStart", transcript=transcript)
+    p["session_id"] = sid
+    session_start(p, str(home))
+    (repo / file).write_text(content)
+    post_tool_use({**p, "tool_name": "Edit", "tool_input": {"file_path": str(repo / file)}}, str(home))
+    git(repo, "add", file)
+    pre_tool_use(
+        {**p, "tool_name": "Bash", "tool_input": {"command": "git commit -m x"}, "transcript_path": transcript},
+        str(home),
+    )
+    git(repo, "commit", "-qm", subject)
+    post_tool_use(
+        {**p, "tool_name": "Bash", "tool_input": {"command": "git commit -m x"}, "transcript_path": transcript},
+        str(home),
+    )
+    stop({**p, "transcript_path": transcript}, str(home))
+    return p
+
+
+def test_why_trace_recall_handoff(repo, home, payload, transcript, monkeypatch, capsys, tmp_path):
+    _write_git_hook(str(repo / ".gitvow" / "git-hooks"))
+    git(repo, "config", "core.hooksPath", ".gitvow/git-hooks")
+    # a transcript whose plan mentions "cache key" for session one
+    t2 = tmp_path / "t2.jsonl"
+    t2.write_text(
+        json.dumps(
+            {
+                "type": "assistant",
+                "message": {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": "Plan: change the cache key to include week start."}],
+                },
+            }
+        )
+        + "\n"
+    )
+    _agent_session(
+        repo, home, payload, "sess-one", "calc.py", "def add(a, b):\n    return a + b\n", "Add calc", str(t2)
+    )
+    # a person edits calc.py and commits without a session
+    (repo / "calc.py").write_text("def add(a, b):\n    return a + b\n\ndef human():\n    return 1\n")
+    git(repo, "commit", "-qam", "human adds helper")
+    # second agent session touches another file and mentions "export"
+    _agent_session(
+        repo, home, payload, "sess-two", "orders.py", "route = '/v1/orders/export'\n", "Add export", transcript
+    )
+    monkeypatch.chdir(repo)
+
+    assert cli.main(["why", "calc.py"]) == 0
+    out = capsys.readouterr().out
+    assert "1 agent commit, 1 human commit, 1 session" in out
+    assert "session sess-one" in out and "cache key" in out and "(person)" in out and "agent share 1.00" in out
+    assert "1 snapshot of this file" in out
+
+    assert cli.main(["trace", "calc.py:1-5"]) == 0
+    out = capsys.readouterr().out
+    assert "agent" in out and "session sess-one" in out and "person" in out
+    assert cli.main(["trace", "calc.py"]) == 0
+    assert cli.main(["trace", "nope.py"]) == 0  # reports the git error instead of crashing
+
+    assert cli.main(["recall", "cache", "key"]) == 0
+    out = capsys.readouterr().out
+    assert "1 session mention" in out and "sess-one" in out and "sess-two" not in out
+    assert cli.main(["recall", "export"]) == 0
+    assert "sess-two" in capsys.readouterr().out
+    assert cli.main(["recall", "zzzunlikely"]) == 0
+    assert "nothing recorded" in capsys.readouterr().out
+    # a session that ended without committing is found through the ledger alone
+    p3 = payload("SessionStart", transcript=str(t2))
+    p3["session_id"] = "sess-three"
+    session_start(p3, str(home))
+    pre_tool_use({**p3, "tool_name": "Bash", "tool_input": {"command": "kubectl apply -f x.yaml"}}, str(home))
+    stop(p3, str(home))
+    assert cli.main(["recall", "week", "start"]) == 0
+    out = capsys.readouterr().out
+    assert "2 sessions mention" in out and "sess-thr" in out and "(ledger only)" in out
+    assert cli.main(["handoff", "--session", "sess-three"]) == 0
+    out = capsys.readouterr().out
+    assert "Open confirmations: 1" in out and "kubectl apply" in out and "Commits this session: none" in out
+
+    (repo / "orders.py").write_text("route = '/v1/orders/export'\nx = 1\n")  # uncommitted work
+    p2 = payload("SessionStart")
+    p2["session_id"] = "sess-two"
+    session_start(p2, str(home))  # resume session two so handoff defaults to it
+    assert cli.main(["handoff"]) == 0
+    out = capsys.readouterr().out
+    assert out.startswith("# Handoff · session sess-two") and "Add export" in out and "orders.py" in out
+    assert "Uncommitted now: 1 file changed" in out and "last snapshot refs/gitvow/snapshots/sess-two/1" in out
+    assert cli.main(["handoff", "--session", "sess-one"]) == 0
+    assert "Add calc" in capsys.readouterr().out
+
+
+def test_handoff_without_session(repo, monkeypatch, capsys):
+    monkeypatch.chdir(repo)
+    assert cli.main(["handoff"]) == 0
+    assert "no session known" in capsys.readouterr().out
+    assert cli.main(["why", "a.txt"]) == 0
+    assert "0 agent commits, 1 human commit" in capsys.readouterr().out