gitvow 0.2.3__tar.gz → 0.4.0__tar.gz

{gitvow-0.2.3/src/gitvow.egg-info → gitvow-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.2.3
+Version: 0.4.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.2.3 → gitvow-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitvow"
-version = "0.2.3"
+version = "0.4.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.2.3 → gitvow-0.4.0}/src/gitvow/cli.py

@@ -13,7 +13,9 @@ from .collect import collect, summarize_text
 from .hooks import HANDLERS, LEGACY_NOTES_REF, notes_ref
 from .install import install_repo, install_user, uninstall_repo, uninstall_user
 from .policy import PolicyError, evaluate, load_policy
+from .providers import QUESTIONS, ask
 from .redact import RedactionError, load_rules, redact
+from .report import build, render_markdown
 from .state import git
 
 
@@ -65,6 +67,26 @@ def cmd_check(a: argparse.Namespace) -> int:
     return 2 if d.blocks else 0
 
 
+def cmd_ask(a: argparse.Namespace) -> int:
+    """Ask every configured provider one question and show the gate's decision."""
+    try:
+        pol = load_policy(os.getcwd())
+    except PolicyError as e:
+        print(f"policy error: {e}", file=sys.stderr)
+        return 2
+    if not pol.get("providers"):
+        print("no providers configured in the active policy", file=sys.stderr)
+        return 1
+    path = a.path or (a.subject if a.question == "gate_bearing" else "")
+    answers = ask(pol, "Edit", {"file_path": path}, os.getcwd(), only=[(a.question, a.subject)])
+    for ans in answers:
+        ev = " — " + "; ".join(ans.evidence) if ans.evidence else ""
+        print(f"{ans.provider}: {ans.answer}{ev}")
+    blocked = any(x.blocks for x in answers)
+    print("decision: " + ("CONFIRM" if blocked else "ALLOW"))
+    return 2 if blocked else 0
+
+
 def cmd_show(a: argparse.Namespace) -> int:
     """Print a commit's trailers and session note."""
     rc, msg, _ = git(["log", "-1", "--format=%H%n%s%n%b", a.commit], os.getcwd())
@@ -94,6 +116,31 @@ def cmd_redact(a: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_report(a: argparse.Namespace) -> int:
+    """Per-commit report for base..head; exit 1 when --require-notes and a trailered commit has no note."""
+    try:
+        r = build(os.getcwd(), a.base, a.head)
+    except ValueError as e:
+        print(f"report error: {e}", file=sys.stderr)
+        return 1
+    print(json.dumps(r, indent=1) if a.json else render_markdown(r), end="" if not a.json else "\n")
+    if a.require_notes and r["missing_notes"]:
+        print(f"missing session notes for: {', '.join(r['missing_notes'])}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def cmd_push_notes(a: argparse.Namespace) -> int:
+    import subprocess
+
+    env = {**os.environ, "GITVOW_PUSHING_NOTES": "1"}  # the pre-push hook must not push the same refs again
+    r = subprocess.run(
+        ["git", "push", a.remote, "refs/notes/gitvow/*:refs/notes/gitvow/*"], env=env, capture_output=True, text=True
+    )
+    print((r.stderr or r.stdout).strip() or "notes pushed", file=sys.stderr if r.returncode else sys.stdout)
+    return 1 if r.returncode else 0
+
+
 def cmd_collect(a: argparse.Namespace) -> int:
     w = collect(os.path.expanduser("~"), a.out)
     print(summarize_text(w))
@@ -138,9 +185,23 @@ def main(argv: list[str] | None = None) -> int:
     s = sub.add_parser("show", help="print a commit's trailers and session note")
     s.add_argument("commit", nargs="?", default="HEAD")
     s.set_defaults(f=cmd_show)
+    s = sub.add_parser("ask", help="ask configured providers a question: gitvow ask route_gate /v1/x --path src/api.py")
+    s.add_argument("question", choices=QUESTIONS)
+    s.add_argument("subject")
+    s.add_argument("--path", default="")
+    s.set_defaults(f=cmd_ask)
     s = sub.add_parser("redact", help="apply built-in redaction plus your rules files to text")
     s.add_argument("text", nargs="+")
     s.set_defaults(f=cmd_redact)
+    s = sub.add_parser("report", help="per-commit report for a range: trailers, notes, attribution, said vs did")
+    s.add_argument("--base", required=True)
+    s.add_argument("--head", default="HEAD")
+    s.add_argument("--json", action="store_true")
+    s.add_argument("--require-notes", action="store_true")
+    s.set_defaults(f=cmd_report)
+    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)
     s = sub.add_parser("collect", help="gather ledger, logs, trailers and notes into one directory")
     s.add_argument("--out", default=os.path.expanduser("~/Desktop"))
     s.set_defaults(f=cmd_collect)

{gitvow-0.2.3 → gitvow-0.4.0}/src/gitvow/hooks/__init__.py

@@ -64,7 +64,7 @@ def pre_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]:
             2,
             f"BLOCKED: tool policy could not be loaded ({e}); refusing all tool calls until the policy is restored.",
         )
-    d = evaluate(pol, tool, inp)
+    d = evaluate(pol, tool, inp, cwd)
     rules, warn = _rules_or_none(cwd, home)
     if d.blocks:
         payload: dict[str, Any] = {"tool": tool, "reason": d.reason, "session_id": h.get("session_id")}

{gitvow-0.2.3 → gitvow-0.4.0}/src/gitvow/install.py

@@ -24,6 +24,17 @@ SELF="$(cd "$(dirname "$0")" && pwd)"; REPOHOOKS="$(cd "$GD/hooks" 2>/dev/null &
 [ -x "$GD/hooks/prepare-commit-msg" ] && [ "$SELF" != "$REPOHOOKS" ] && exec "$GD/hooks/prepare-commit-msg" "$@"
 exit 0
 """
+PRE_PUSH_HOOK = """#!/bin/sh
+# gitvow: push session notes (refs/notes/gitvow/*) to the same remote whenever a branch is pushed.
+# The inner push re-enters this hook; GITVOW_PUSHING_NOTES stops the recursion.
+REMOTE="$1"
+if [ -z "$GITVOW_PUSHING_NOTES" ] && [ -n "$REMOTE" ] && git for-each-ref --count=1 refs/notes/gitvow/ | grep -q .; then
+  GITVOW_PUSHING_NOTES=1 git push --quiet "$REMOTE" 'refs/notes/gitvow/*:refs/notes/gitvow/*' 2>/dev/null || true
+fi
+GD="$(git rev-parse --git-dir)"; SELF="$(cd "$(dirname "$0")" && pwd)"; REPOHOOKS="$(cd "$GD/hooks" 2>/dev/null && pwd || true)"
+[ -x "$GD/hooks/pre-push" ] && [ "$SELF" != "$REPOHOOKS" ] && exec "$GD/hooks/pre-push" "$@"
+exit 0
+"""
 MARKER = "gitvow hook "
 NOTES_GLOB = "refs/notes/gitvow/*"
 NOTES_KEYS = ("notes.displayRef", "notes.rewriteRef")
@@ -106,11 +117,12 @@ def unmerge_settings(path: str) -> None:
 
 def _write_git_hook(dirpath: str) -> str:
     os.makedirs(dirpath, exist_ok=True)
-    p = os.path.join(dirpath, "prepare-commit-msg")
-    with open(p, "w") as fh:
-        fh.write(GIT_HOOK)
-    os.chmod(p, 0o755)  # noqa: S103  # nosec B103 - git runs hooks as the invoking user; must be executable
-    return p
+    for name, body in (("prepare-commit-msg", GIT_HOOK), ("pre-push", PRE_PUSH_HOOK)):
+        p = os.path.join(dirpath, name)
+        with open(p, "w") as fh:
+            fh.write(body)
+        os.chmod(p, 0o755)  # noqa: S103  # nosec B103 - git runs hooks as the invoking user; must be executable
+    return os.path.join(dirpath, "prepare-commit-msg")
 
 
 def install_user(home: str, cmd_prefix: str | None = None) -> list[str]:

{gitvow-0.2.3 → gitvow-0.4.0}/src/gitvow/policy.py

@@ -10,6 +10,8 @@ import subprocess
 from dataclasses import dataclass
 from typing import Any
 
+from . import providers as _providers
+
 DEFAULT_POLICY_PATH = os.path.join(os.path.dirname(__file__), "default_policy.json")
 
 
@@ -63,9 +65,18 @@ def _validate(pol: dict[str, Any], path: str) -> None:
                 re.compile(pat)
             except re.error as e:
                 raise PolicyError(f"{path}: bad regex in {key}: {pat} ({e})") from e
-
-
-def evaluate(pol: dict[str, Any], tool: str, tool_input: dict[str, Any]) -> Decision:
+    provs = pol.get("providers", [])
+    if not isinstance(provs, list):
+        raise PolicyError(f"{path}: providers must be a list")
+    for prov in provs:
+        if not isinstance(prov, dict) or not prov.get("name") or not prov.get("command"):
+            raise PolicyError(f"{path}: each provider needs 'name' and 'command'")
+        bad = [q for q in prov.get("questions", []) if q not in _providers.QUESTIONS]
+        if bad:
+            raise PolicyError(f"{path}: provider {prov['name']} lists unknown questions {bad}")
+
+
+def evaluate(pol: dict[str, Any], tool: str, tool_input: dict[str, Any], cwd: str | None = None) -> Decision:
     text = tool_input.get("command", "") if tool == "Bash" else ""
     path = tool_input.get("file_path", "") or tool_input.get("notebook_path", "")
     if tool == "Bash":
@@ -85,6 +96,10 @@ def evaluate(pol: dict[str, Any], tool: str, tool_input: dict[str, Any]) -> Deci
         allow = pol.get("mcp_allow", [])
         if allow and not any(re.fullmatch(p, tool) for p in allow):
             return Decision("confirm", "MCP tool not on allow list", tool)
+    if pol.get("providers") and tool in ("Edit", "Write", "MultiEdit", "NotebookEdit"):
+        hits = [a for a in _providers.ask(pol, tool, tool_input, cwd) if a.blocks]
+        if hits:
+            return Decision("confirm", "; ".join(h.text() for h in hits[:3]), path)
     clf = pol.get("llm_classifier") or {}
     if clf.get("enabled") and clf.get("command"):
         return _classify(clf["command"], tool, tool_input, text or path or tool)

gitvow-0.4.0/src/gitvow/providers.py

@@ -0,0 +1,126 @@
+"""Providers: external programs the gate asks factual questions (gate_bearing, route_gate, route_callers)."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import subprocess
+from dataclasses import dataclass, field
+from typing import Any
+
+PROTOCOL = 1
+QUESTIONS = ("gate_bearing", "route_gate", "route_callers")
+EDIT_TOOLS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
+ROUTE_RE = re.compile(r"""["'`](/[A-Za-z0-9_\-./{}:*$]*)["'`]""")
+
+
+@dataclass
+class Answer:
+    provider: str
+    question: str
+    subject: str
+    answer: str  # yes | no | unknown | failed
+    evidence: list[str] = field(default_factory=list)
+
+    @property
+    def blocks(self) -> bool:
+        return self.answer in ("yes", "failed")
+
+    def text(self) -> str:
+        why = "; ".join(self.evidence[:4]) if self.evidence else ""
+        if self.answer == "failed":
+            return f"provider {self.provider} unavailable for {self.question} {self.subject}"
+        return f"provider {self.provider}: {self.question} {self.subject}" + (f": {why}" if why else "")
+
+
+def route_literals(text: str) -> list[str]:
+    """Quoted strings that look like routes: begin with '/', no spaces, at least one more character."""
+    out: list[str] = []
+    for m in ROUTE_RE.finditer(text or ""):
+        r = m.group(1)
+        if len(r) > 1 and not r.startswith("//") and "." not in os.path.basename(r) and r not in out:
+            out.append(r)
+    return out
+
+
+def questions_for(tool: str, tool_input: dict[str, Any]) -> list[tuple[str, str]]:
+    """(question, subject) pairs the gate should ask for this tool call."""
+    if tool not in EDIT_TOOLS:
+        return []
+    path = tool_input.get("file_path") or tool_input.get("notebook_path") or ""
+    qs: list[tuple[str, str]] = []
+    if path:
+        qs.append(("gate_bearing", path))
+    old, new = "", ""
+    if tool == "Edit":
+        old, new = str(tool_input.get("old_string") or ""), str(tool_input.get("new_string") or "")
+    elif tool == "MultiEdit":
+        for e in tool_input.get("edits") or []:
+            old += "\n" + str(e.get("old_string") or "")
+            new += "\n" + str(e.get("new_string") or "")
+    elif tool == "Write":
+        new = str(tool_input.get("content") or "")
+    before, after = set(route_literals(old)), set(route_literals(new))
+    qs += [("route_gate", r) for r in sorted(after - before)]
+    qs += [("route_callers", r) for r in sorted(before - after)]
+    return qs
+
+
+def _run(prov: dict[str, Any], question: str, subject: str, repo: str, path: str, tool: str) -> Answer:
+    name = str(prov.get("name") or "provider")
+    req = {
+        "protocol": PROTOCOL,
+        "question": question,
+        "subject": subject,
+        "repo": repo,
+        "path": path,
+        "tool_name": tool,
+    }
+    try:
+        argv = shlex.split(str(prov.get("command") or ""))
+        if not argv:
+            return Answer(name, question, subject, "failed", ["empty command"])
+        r = subprocess.run(
+            argv,
+            input=json.dumps(req),
+            capture_output=True,
+            text=True,
+            timeout=float(prov.get("timeout") or 10),
+            check=False,
+            cwd=repo or None,
+        )
+        if r.returncode != 0:
+            return Answer(name, question, subject, "failed", [f"exit {r.returncode}"])
+        data = json.loads(r.stdout)
+        ans = str(data.get("answer", "unknown")).lower()
+        if ans not in ("yes", "no", "unknown"):
+            return Answer(name, question, subject, "failed", ["bad answer"])
+        ev = [str(e)[:200] for e in (data.get("evidence") or [])[:8]]
+        return Answer(name, question, subject, ans, ev)
+    except (OSError, subprocess.TimeoutExpired, ValueError, AttributeError) as e:
+        return Answer(name, question, subject, "failed", [type(e).__name__])
+
+
+def ask(
+    pol: dict[str, Any],
+    tool: str,
+    tool_input: dict[str, Any],
+    cwd: str | None = None,
+    only: list[tuple[str, str]] | None = None,
+) -> list[Answer]:
+    provs = pol.get("providers") or []
+    if not provs:
+        return []
+    repo = cwd or os.getcwd()
+    path = str(tool_input.get("file_path") or tool_input.get("notebook_path") or "")
+    if path and os.path.isabs(path):
+        rel = os.path.relpath(path, repo)
+        path = rel if not rel.startswith("..") else path
+    answers: list[Answer] = []
+    for q, subj in only if only is not None else questions_for(tool, {**tool_input, "file_path": path}):
+        for prov in provs:
+            if q in (prov.get("questions") or QUESTIONS):
+                answers.append(_run(prov, q, subj, repo, path, tool))
+    return answers

gitvow-0.4.0/src/gitvow/report.py

@@ -0,0 +1,140 @@
+"""Per-commit report for a range: trailers paired with session notes, attribution, and said-vs-did."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any
+
+from .hooks import LEGACY_NOTES_REF, notes_ref
+from .state import git
+
+TRAILER_RE = re.compile(r"^Gitvow-Session:\s*(\S+)", re.M)
+STEP_RE = re.compile(r"^Gitvow-Step:\s*(\d+)", re.M)
+
+
+def _note_for(cwd: str, sha: str, session_id: str) -> dict[str, Any] | None:
+    for ref in (notes_ref(session_id), 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 _changed_files(cwd: str, sha: str) -> list[str]:
+    _, out, _ = git(["show", "--name-only", "--format=", sha], cwd)
+    return [ln for ln in out.splitlines() if ln.strip()]
+
+
+def said_vs_did(plan: str, files: list[str]) -> dict[str, list[str]]:
+    """Which changed files does the stated plan mention (by path or basename, case-insensitive)?"""
+    low = plan.lower()
+    mentioned, unmentioned = [], []
+    for f in files:
+        base = os.path.basename(f).lower()
+        stem = os.path.splitext(base)[0]
+        if f.lower() in low or base in low or (len(stem) > 3 and stem in low):
+            mentioned.append(f)
+        else:
+            unmentioned.append(f)
+    return {"mentioned": mentioned, "unmentioned": unmentioned}
+
+
+def build(cwd: str, base: str, head: str = "HEAD") -> dict[str, Any]:
+    rc, out, err = git(["log", "--reverse", "--format=%H%x00%s%x00%B%x01", f"{base}..{head}"], cwd)
+    if rc != 0:
+        raise ValueError(err or f"cannot list {base}..{head}")
+    commits: list[dict[str, Any]] = []
+    for rec in out.split("\x01"):
+        rec = rec.strip("\n")
+        if not rec.strip():
+            continue
+        sha, subject, body = rec.split("\x00", 2)
+        m = TRAILER_RE.search(body)
+        entry: dict[str, Any] = {"sha": sha, "short": sha[:7], "subject": subject, "files": _changed_files(cwd, sha)}
+        if not m:
+            entry["kind"] = "human"
+            commits.append(entry)
+            continue
+        sid = m.group(1)
+        sm = STEP_RE.search(body)
+        entry.update({"kind": "agent", "session_id": sid, "step": int(sm.group(1)) if sm else None})
+        note = _note_for(cwd, sha, sid)
+        entry["note_found"] = note is not None
+        if note:
+            plan = note.get("last_stated_plan") or ""
+            att = note.get("attribution") or {}
+            entry.update(
+                {
+                    "plan": plan,
+                    "tools_used": note.get("tools_used", []),
+                    "tool_calls": note.get("tool_calls_so_far"),
+                    "turns": note.get("assistant_turns_so_far"),
+                    "attribution": {
+                        "files_in_commit": att.get("files_in_commit"),
+                        "touched_by_agent": att.get("touched_by_agent"),
+                        "agent_share": att.get("agent_share"),
+                        "lines_changed_by_human_after_agent": att.get("lines_changed_by_human_after_agent"),
+                    },
+                    "said_vs_did": said_vs_did(plan, entry["files"]),
+                }
+            )
+        commits.append(entry)
+    agent = [c for c in commits if c["kind"] == "agent"]
+    return {
+        "base": base,
+        "head": head,
+        "commits": commits,
+        "agent_commits": len(agent),
+        "human_commits": len(commits) - len(agent),
+        "missing_notes": [c["short"] for c in agent if not c["note_found"]],
+    }
+
+
+def render_markdown(r: dict[str, Any]) -> str:
+    lines = [
+        f"## gitvow: {r['agent_commits']} agent commit{'s' if r['agent_commits'] != 1 else ''}, "
+        f"{r['human_commits']} human commit{'s' if r['human_commits'] != 1 else ''}",
+        "",
+    ]
+    if r["missing_notes"]:
+        lines += [
+            f"> **Missing session notes** for {', '.join(r['missing_notes'])}. "
+            "The author's notes were not pushed; run `gitvow push-notes` or `git push origin 'refs/notes/gitvow/*'`.",
+            "",
+        ]
+    for c in r["commits"]:
+        if c["kind"] == "human":
+            lines += [f"### {c['short']} {c['subject']} — no session trailer (made by a person)", ""]
+            continue
+        sid = c["session_id"][:8]
+        lines.append(
+            f"### {c['short']} {c['subject']} — session {sid}, step {c['step'] if c['step'] is not None else '?'}"
+        )
+        if not c["note_found"]:
+            lines += ["**Session note:** missing (not pushed)", ""]
+            continue
+        plan = c["plan"].strip().replace("\n", " ")
+        lines.append(f"**Plan:** {plan[:400] if plan else '(none stated before committing)'}")
+        tools = ", ".join(c["tools_used"]) or "none recorded"
+        lines.append(f"**Tools:** {tools} · {c['tool_calls']} tool calls · {c['turns']} turns")
+        a = c["attribution"]
+        share = "n/a" if a["agent_share"] is None else f"{a['agent_share']:.2f}"
+        lines.append(
+            f"**Attribution:** {a['files_in_commit']} file{'s' if a['files_in_commit'] != 1 else ''}, "
+            f"agent share {share}, {a['lines_changed_by_human_after_agent'] or 0} lines changed by a human after the agent"
+        )
+        svd = c["said_vs_did"]
+        parts = []
+        if svd["mentioned"]:
+            parts.append(", ".join(svd["mentioned"]) + " mentioned in plan ✓")
+        if svd["unmentioned"]:
+            parts.append(", ".join(svd["unmentioned"]) + " **not mentioned in plan**")
+        if not plan:
+            parts.append("no plan to compare")
+        lines += ["**Said vs did:** " + " · ".join(parts), ""]
+    return "\n".join(lines).rstrip() + "\n"

{gitvow-0.2.3 → gitvow-0.4.0}/src/gitvow/selftest.py

@@ -6,6 +6,7 @@ import json
 import os
 import shutil
 import subprocess
+import sys
 import tempfile
 
 from .hooks import post_tool_use, pre_tool_use, session_start, stop
@@ -66,6 +67,24 @@ def run() -> int:
                 "deny: destructive MCP tool",
             )
         )
+        prov = (
+            f'{sys.executable} -c "import sys,json;q=json.load(sys.stdin);'
+            "print(json.dumps({'answer':'yes' if q['question']=='route_gate' else 'no',"
+            "'evidence':['route not covered by authorization (selftest provider)']}))\""
+        )
+        os.makedirs(os.path.join(repo, ".gitvow"), exist_ok=True)
+        with open(os.path.join(repo, ".gitvow", "policy.json"), "w") as fh:
+            json.dump({"providers": [{"name": "selftest", "command": prov}]}, fh)
+        code, msg = pre_tool_use(
+            {
+                **base,
+                "tool_name": "Edit",
+                "tool_input": {"file_path": "api.py", "old_string": "", "new_string": '"/v1/new"'},
+            },
+            home,
+        )
+        results.append((code == 2 and "route not covered" in msg, "confirm: provider says new route is unauthorised"))
+        os.remove(os.path.join(repo, ".gitvow", "policy.json"))
         with open(os.path.join(repo, "a.txt"), "a") as fh:
             fh.write("b\n")
         post_tool_use({**base, "tool_name": "Edit", "tool_input": {"file_path": "a.txt"}}, home)

{gitvow-0.2.3 → gitvow-0.4.0/src/gitvow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.2.3
+Version: 0.4.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.2.3 → gitvow-0.4.0}/src/gitvow.egg-info/SOURCES.txt

@@ -8,7 +8,9 @@ src/gitvow/collect.py
 src/gitvow/default_policy.json
 src/gitvow/install.py
 src/gitvow/policy.py
+src/gitvow/providers.py
 src/gitvow/redact.py
+src/gitvow/report.py
 src/gitvow/selftest.py
 src/gitvow/state.py
 src/gitvow/transcript.py
@@ -24,4 +26,6 @@ tests/test_hooks.py
 tests/test_install_cli.py
 tests/test_packaging.py
 tests/test_policy.py
-tests/test_redact.py
+tests/test_providers.py
+tests/test_redact.py
+tests/test_report.py

gitvow-0.4.0/tests/test_providers.py

@@ -0,0 +1,160 @@
+import json
+import sys
+from pathlib import Path
+
+from gitvow import cli
+from gitvow.hooks import pre_tool_use
+from gitvow.policy import evaluate
+from gitvow.providers import questions_for, route_literals
+
+ROOT = Path(__file__).resolve().parents[1]
+EXAMPLE = ROOT / "examples" / "providers" / "static_facts.py"
+
+
+def test_route_literals_and_questions():
+    txt = 'a = "/v1/orders"; b = \'/v1/orders/{id}\'; c = "/static/app.js"; d = "//comment"; e = "/"; f = "/v1/orders"'
+    assert route_literals(txt) == ["/v1/orders", "/v1/orders/{id}"]
+    qs = questions_for(
+        "Edit",
+        {"file_path": "api.py", "old_string": '@app.get("/old")', "new_string": '@app.get("/new")\n@app.get("/old2")'},
+    )
+    assert qs == [
+        ("gate_bearing", "api.py"),
+        ("route_gate", "/new"),
+        ("route_gate", "/old2"),
+        ("route_callers", "/old"),
+    ]
+    assert questions_for("Write", {"file_path": "x.py", "content": 'r("/w")'}) == [
+        ("gate_bearing", "x.py"),
+        ("route_gate", "/w"),
+    ]
+    assert questions_for("Bash", {"command": 'echo "/v1/x"'}) == []
+
+
+def _facts(tmp_path):
+    f = tmp_path / "facts.json"
+    f.write_text(
+        json.dumps(
+            {
+                "gate_bearing": ["auth/AuthorizeWhitelistedPaths.java", "deploy/values/production-*.yaml"],
+                "whitelist_file": "auth/AuthorizeWhitelistedPaths.java",
+                "authorized_routes": ["/v1/orders", "/v1/orders/{id}"],
+                "callers": {"/v1/orders": ["client-orch (OrdersClient.java:88)"]},
+            }
+        )
+    )
+    return f
+
+
+def _policy(tmp_path, command):
+    return {"providers": [{"name": "facts", "command": command}]}
+
+
+def test_provider_confirms_with_evidence(tmp_path):
+    pol = _policy(tmp_path, f"{sys.executable} {EXAMPLE} --facts {_facts(tmp_path)}")
+    d = evaluate(
+        pol,
+        "Edit",
+        {"file_path": "src/api/Orders.java", "old_string": "x", "new_string": '@Path("/v1/orders/export")'},
+        str(tmp_path),
+    )
+    assert d.outcome == "confirm" and "not covered by any authorization rule" in d.reason
+    assert "AuthorizeWhitelistedPaths.java" in d.reason
+    d = evaluate(
+        pol,
+        "Edit",
+        {"file_path": "src/api/Orders.java", "old_string": "x", "new_string": '@Path("/v1/orders/{id}")'},
+        str(tmp_path),
+    )
+    assert d.outcome == "allow"  # listed as authorized
+    d = evaluate(
+        pol,
+        "Edit",
+        {"file_path": "src/api/Orders.java", "old_string": '@Path("/v1/orders")', "new_string": ""},
+        str(tmp_path),
+    )
+    assert d.outcome == "confirm" and "client-orch" in d.reason
+    d = evaluate(
+        pol,
+        "Write",
+        {"file_path": str(tmp_path / "deploy/values/production-in.yaml"), "content": "a: 1"},
+        str(tmp_path),
+    )
+    assert d.outcome == "confirm" and "gate-bearing" in d.reason
+    assert (
+        evaluate(pol, "Edit", {"file_path": "README.md", "old_string": "a", "new_string": "b"}, str(tmp_path)).outcome
+        == "allow"
+    )
+    assert evaluate(pol, "Bash", {"command": 'echo "/v1/new"'}, str(tmp_path)).outcome == "allow"
+
+
+def test_provider_failure_means_confirm(tmp_path):
+    for cmd in (
+        "/nonexistent/provider",
+        f"{sys.executable} -c \"print('not json')\"",
+        f"{sys.executable} -c 'import sys; sys.exit(3)'",
+        "",
+    ):
+        pol = _policy(tmp_path, cmd)
+        d = evaluate(pol, "Edit", {"file_path": "a.py", "old_string": "", "new_string": ""}, str(tmp_path))
+        assert d.outcome == "confirm" and "unavailable" in d.reason, cmd
+    pol = _policy(tmp_path, f"{sys.executable} -c 'import time; time.sleep(5)'")
+    pol["providers"][0]["timeout"] = 0.5
+    assert evaluate(pol, "Edit", {"file_path": "a.py"}, str(tmp_path)).outcome == "confirm"
+
+
+def test_unknown_answer_does_not_block(tmp_path):
+    pol = _policy(tmp_path, f'{sys.executable} -c "print(\'{{\\"answer\\": \\"unknown\\"}}\')"')
+    assert evaluate(pol, "Edit", {"file_path": "a.py"}, str(tmp_path)).outcome == "allow"
+
+
+def test_provider_questions_filter_and_validation(tmp_path):
+    from gitvow.policy import PolicyError, load_policy
+
+    (tmp_path / ".gitvow").mkdir()
+    (tmp_path / ".gitvow" / "policy.json").write_text(
+        json.dumps({"providers": [{"name": "x", "command": "y", "questions": ["nope"]}]})
+    )
+    try:
+        load_policy(str(tmp_path), str(tmp_path / "h"))
+        raise AssertionError("expected PolicyError")
+    except PolicyError as e:
+        assert "unknown questions" in str(e)
+    (tmp_path / ".gitvow" / "policy.json").write_text(json.dumps({"providers": [{"name": "x"}]}))
+    try:
+        load_policy(str(tmp_path), str(tmp_path / "h"))
+        raise AssertionError("expected PolicyError")
+    except PolicyError:
+        pass
+    pol = _policy(tmp_path, f"{sys.executable} {EXAMPLE} --facts {_facts(tmp_path)}")
+    pol["providers"][0]["questions"] = ["gate_bearing"]  # route questions not asked of this provider
+    d = evaluate(pol, "Edit", {"file_path": "a.py", "old_string": "", "new_string": '"/v1/zzz"'}, str(tmp_path))
+    assert d.outcome == "allow"
+
+
+def test_hook_and_cli_ask_end_to_end(repo, home, payload, tmp_path, monkeypatch, capsys):
+    facts = _facts(tmp_path)
+    (repo / ".gitvow").mkdir()
+    (repo / ".gitvow" / "policy.json").write_text(
+        json.dumps({"providers": [{"name": "facts", "command": f"{sys.executable} {EXAMPLE} --facts {facts}"}]})
+    )
+    code, msg = pre_tool_use(
+        payload(
+            "PreToolUse",
+            "Edit",
+            {"file_path": str(repo / "src/Orders.java"), "old_string": "", "new_string": '@Path("/v1/orders/export")'},
+        ),
+        str(home),
+    )
+    assert code == 2 and "CONFIRMATION REQUIRED" in msg and "AuthorizeWhitelistedPaths.java" in msg
+    log = (repo / ".git" / "gitvow-hooks.log").read_text()
+    assert '"kind": "confirm_required"' in log and "provider facts" in log
+    monkeypatch.chdir(repo)
+    assert cli.main(["ask", "route_gate", "/v1/orders/export", "--path", "src/Orders.java"]) == 2
+    out = capsys.readouterr().out
+    assert "facts: yes" in out and "decision: CONFIRM" in out
+    assert cli.main(["ask", "route_gate", "/v1/orders"]) == 0
+    assert "decision: ALLOW" in capsys.readouterr().out
+    assert cli.main(["ask", "gate_bearing", "auth/AuthorizeWhitelistedPaths.java"]) == 2
+    (repo / ".gitvow" / "policy.json").write_text("{}")
+    assert cli.main(["ask", "gate_bearing", "x"]) == 1

gitvow-0.4.0/tests/test_report.py

@@ -0,0 +1,84 @@
+import json
+import time
+
+from gitvow import cli
+from gitvow.hooks import post_tool_use, pre_tool_use, session_start
+from gitvow.install import _write_git_hook
+from gitvow.report import build, render_markdown, said_vs_did
+from tests.conftest import git
+
+
+def test_said_vs_did_matches_path_basename_or_stem():
+    r = said_vs_did(
+        "Fix the cache key in QueryCacheHelper.java and touch calc", ["a/QueryCacheHelper.java", "calc.py", "x/util.go"]
+    )
+    assert r == {"mentioned": ["a/QueryCacheHelper.java", "calc.py"], "unmentioned": ["x/util.go"]}
+    assert said_vs_did("", ["a.py"]) == {"mentioned": [], "unmentioned": ["a.py"]}
+
+
+def _agent_commit(repo, home, payload, transcript, sid, text):
+    p = payload("SessionStart", transcript=transcript)
+    p["session_id"] = sid
+    session_start(p, str(home))
+    (repo / "a.txt").write_text(text)
+    post_tool_use({**p, "tool_name": "Edit", "tool_input": {"file_path": "a.txt"}}, str(home))
+    pre_tool_use({**p, "tool_name": "Bash", "tool_input": {"command": "git commit -m x"}}, str(home))
+    git(repo, "commit", "-qam", f"agent {sid}")
+    post_tool_use({**p, "tool_name": "Bash", "tool_input": {"command": "git commit -m x"}}, str(home))
+
+
+def test_report_pairs_trailers_with_notes_and_flags_missing(repo, home, payload, transcript, monkeypatch, capsys):
+    _write_git_hook(str(repo / ".gitvow" / "git-hooks"))
+    git(repo, "config", "core.hooksPath", ".gitvow/git-hooks")
+    base = git(repo, "rev-parse", "HEAD")
+    _agent_commit(repo, home, payload, transcript, "s-aaa", "one\n")
+    (repo / "h.txt").write_text("human\n")
+    git(repo, "add", "h.txt")
+    git(repo, "commit", "-qm", "human commit")
+    _agent_commit(repo, home, payload, transcript, "s-bbb", "two\n")
+    git(repo, "update-ref", "-d", "refs/notes/gitvow/s-bbb")  # simulate notes never pushed
+    r = build(str(repo), base, "HEAD")
+    assert r["agent_commits"] == 2 and r["human_commits"] == 1 and len(r["missing_notes"]) == 1
+    kinds = [c["kind"] for c in r["commits"]]
+    assert kinds == ["agent", "human", "agent"]
+    first = r["commits"][0]
+    assert first["note_found"] and first["attribution"]["agent_share"] == 1.0 and first["step"] == 1
+    assert "[github-token]" in first["plan"]  # redacted plan travels into the report
+    assert first["said_vs_did"]["unmentioned"] == ["a.txt"]
+    md = render_markdown(r)
+    assert "2 agent commits, 1 human commit" in md and "Missing session notes" in md
+    assert "made by a person" in md and "not mentioned in plan" in md and "ghp_" not in md
+    monkeypatch.chdir(repo)
+    assert cli.main(["report", "--base", base]) == 0
+    assert cli.main(["report", "--base", base, "--require-notes"]) == 1
+    assert "missing session notes" in capsys.readouterr().err
+    assert cli.main(["report", "--base", base, "--json"]) == 0
+    assert json.loads(capsys.readouterr().out)["agent_commits"] == 2
+    assert cli.main(["report", "--base", "nonexistent-rev"]) == 1
+
+
+def test_pre_push_hook_pushes_notes_with_branch(repo, home, tmp_path):
+    remote = tmp_path / "remote.git"
+    git(remote.parent, "init", "-q", "--bare", str(remote))
+    git(repo, "remote", "add", "origin", str(remote))
+    _write_git_hook(str(repo / ".gitvow" / "git-hooks"))
+    git(repo, "config", "core.hooksPath", ".gitvow/git-hooks")
+    assert (repo / ".gitvow" / "git-hooks" / "pre-push").exists()
+    git(repo, "notes", "--ref=gitvow/s1", "add", "-m", "gitvow-session\n{}", "HEAD")
+    branch = git(repo, "branch", "--show-current")
+    git(repo, "push", "-q", "origin", branch)
+    assert git(remote, "for-each-ref", "--format=%(refname)", "refs/notes/gitvow/") == "refs/notes/gitvow/s1"
+    # push-notes by hand, and idempotent second push
+    (repo / "a.txt").write_text("n\n")
+    git(repo, "commit", "-qam", "n")
+    git(repo, "notes", "--ref=gitvow/s2", "add", "-m", "gitvow-session\n{}", "HEAD")
+    import os
+
+    cwd = os.getcwd()
+    os.chdir(repo)
+    try:
+        assert cli.main(["push-notes"]) == 0
+    finally:
+        os.chdir(cwd)
+    assert "refs/notes/gitvow/s2" in git(remote, "for-each-ref", "--format=%(refname)", "refs/notes/gitvow/")
+    assert time.time() > 0