gitvow 0.12.0__tar.gz → 0.12.2__tar.gz

{gitvow-0.12.0/src/gitvow.egg-info → gitvow-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.12.0
+Version: 0.12.2
 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.12.0 → gitvow-0.12.2}/pyproject.toml

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

@@ -57,6 +57,9 @@ def cmd_hook(a: argparse.Namespace) -> int:
         worst = max(worst, code)
         if msg:
             messages.append(msg)
+    if a.event == "SessionStart" and worst == 0 and messages and not exe and agent not in ("cursor", "copilot"):
+        print("\n".join(messages))  # SessionStart stdout becomes context for the agent
+        return 0
     try:
         exit_code, out, err = (
             external_respond(exe, worst, "\n".join(messages)) if exe else respond(agent, worst, "\n".join(messages))
@@ -132,7 +135,79 @@ def cmd_decisions(a: argparse.Namespace) -> int:
     if a.json:
         print(json.dumps(dec.open_findings(cwd), indent=1))
         return 0
-    print(dec.card(cwd, for_agent=False), end="")
+    try:
+        pol = load_policy(cwd)
+    except PolicyError:
+        pol = None
+    print(dec.card(cwd, for_agent=False, pol=pol), end="")
+    return 0
+
+
+def cmd_rules(a: argparse.Namespace) -> int:
+    """Earned rules from the decision history; --write puts them into an agent instruction file."""
+    from .rules import INSTRUCTION_FILES, derive, render, write_section
+
+    cwd = os.getcwd()
+    try:
+        pol = load_policy(cwd)
+    except PolicyError as e:
+        print(f"policy error: {e}", file=sys.stderr)
+        return 2
+    d = derive(cwd, pol)
+    if a.json:
+        print(json.dumps(d, indent=1))
+        return 0
+    if a.write:
+        from .state import toplevel
+
+        top = toplevel(cwd) or cwd
+        target = a.file or INSTRUCTION_FILES.get(a.agent, "CLAUDE.md")
+        print(write_section(os.path.join(top, target), render(d)))
+        return 0
+    text = render(d, for_agent=False)
+    if not text:
+        print(
+            f"no earned rules yet: a finding becomes one after {d['threshold']} consistent answers by authorities "
+            f"(decisions.rule_threshold), confirmed within {d['decay_days']} days."
+        )
+        if d["candidates"]:
+            for r in d["candidates"]:
+                print(f"  {r['finding']}: {r['answer']} {r['count']} times (last {r['last']} by {', '.join(r['by'])})")
+        return 0
+    print(text, end="")
+    return 0
+
+
+def cmd_revisit(a: argparse.Namespace) -> int:
+    """Answer a decision already on the branch again; the record keeps both."""
+    cwd = os.getcwd()
+    try:
+        pol = load_policy(cwd)
+        rules = load_rules(cwd, os.path.expanduser("~"))
+    except (PolicyError, RedactionError) as e:
+        print(str(e), file=sys.stderr)
+        return 2
+    if not a.answer:
+        try:
+            ds = dec.decisions_of(cwd, a.commit)
+        except ValueError as e:
+            print(str(e), file=sys.stderr)
+            return 1
+        if not ds:
+            print(f"{a.commit}: no decision trailers")
+            return 0
+        for d in ds:
+            extra = (f" by {d['by']}" if d.get("by") else "") + (f" scope={d['scope']}" if d.get("scope") else "")
+            print(f"{d['n']}. {d['answer']}: {d['finding']}{extra}")
+        print("revisit with: gitvow revisit <commit> accept|decline [--finding n]", file=sys.stderr)
+        return 0
+    try:
+        head, line = dec.revisit(cwd, a.commit, a.answer, pol, a.finding, a.scope, a.reason, a.by, rules)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    print(line)
+    print(f"recorded as an empty commit {head[:7]}; the earlier trailer stays on {a.commit}", file=sys.stderr)
     return 0
 
 
@@ -411,6 +486,26 @@ def main(argv: list[str] | None = None) -> int:
     s = sub.add_parser("decisions", help="the card: open findings in this repository with evidence and the record")
     s.add_argument("--json", action="store_true")
     s.set_defaults(f=cmd_decisions)
+    s = sub.add_parser(
+        "rules", help="earned rules from the decision history; --write updates the agent instruction file"
+    )
+    s.add_argument("--json", action="store_true")
+    s.add_argument("--write", action="store_true", help="write the managed section into the instruction file")
+    s.add_argument(
+        "--agent",
+        default="claude",
+        help="which agent's instruction file (claude, codex, gemini, cursor, copilot, factory)",
+    )
+    s.add_argument("--file", help="instruction file path, overriding --agent")
+    s.set_defaults(f=cmd_rules)
+    s = sub.add_parser("revisit", help="answer a decision already on the branch again: gitvow revisit <commit> accept")
+    s.add_argument("commit")
+    s.add_argument("answer", nargs="?", choices=["accept", "decline"])
+    s.add_argument("--finding", help="which decision on the commit, when it carries several")
+    s.add_argument("--scope")
+    s.add_argument("--reason")
+    s.add_argument("--by")
+    s.set_defaults(f=cmd_revisit)
     s = sub.add_parser("decide", help="record a person's answer: gitvow decide 1 accept --scope staging")
     s.add_argument("finding", help="finding number from `gitvow decisions`, or 'all'")
     s.add_argument("answer", choices=["accept", "decline"])

{gitvow-0.12.0 → gitvow-0.12.2}/src/gitvow/decisions.py

@@ -14,6 +14,7 @@ from .redact import redact
 from .state import git, load_state, save_state
 
 TRAILER_RE = re.compile(r"^Gitvow-(Accepted|Declined|Open):\s*(.+?)(?: by (\S+))?(?: scope=(\S+))?(?:: (.*))?$", re.M)
+REVISITS_RE = re.compile(r"^Gitvow-Revisits:\s*([0-9a-f]{7,40})\b", re.M)
 MAX_EVIDENCE = 8
 HISTORY_COMMITS = 3000
 
@@ -78,11 +79,13 @@ def identity(cwd: str, by: str | None = None) -> tuple[str, str, str]:
 
 def authority(pol: dict[str, Any], ident: str, email: str, name: str) -> str:
     """'policy' when named under decisions.authorities, 'commit-access' when no list is configured, else 'none'."""
-    auth = [str(a).lower() for a in (pol.get("decisions") or {}).get("authorities") or []]
-    if not auth:
+    listed = [str(a).lower() for a in (pol.get("decisions") or {}).get("authorities") or []]
+    if not listed:
         return "commit-access"
+    auth = set(listed) | {a.split("@", 1)[0] for a in listed if "@" in a}  # an email also names its local part
     mine = {ident.lower(), email.lower(), (email.split("@", 1)[0] if email else "").lower(), name.lower()}
-    return "policy" if mine & set(auth) else "none"
+    mine.discard("")
+    return "policy" if mine & auth else "none"
 
 
 def parse_trailers(body: str) -> list[dict[str, Any]]:
@@ -100,8 +103,34 @@ def parse_trailers(body: str) -> list[dict[str, Any]]:
     return out
 
 
-def history(cwd: str, finding: str, limit: int = HISTORY_COMMITS) -> list[dict[str, Any]]:
-    """Earlier decisions on the same finding in this branch's history, newest first."""
+SESSION_RE = re.compile(r"^Gitvow-Session:\s*(\S+)", re.M)
+
+
+def _note_decisions(cwd: str, sha: str, body: str) -> dict[str, dict[str, Any]]:
+    """finding -> note entry for a commit, when its session note is available locally."""
+    import json
+
+    m = SESSION_RE.search(body)
+    if not m:
+        return {}
+    sid = re.sub(r"[^A-Za-z0-9._-]", "_", m.group(1))
+    rc, note, _ = git(["notes", f"--ref=gitvow/{sid}", "show", sha], cwd)
+    if rc != 0 or not note.startswith("gitvow-session"):
+        return {}
+    try:
+        data = json.loads(note.split("\n", 1)[1])
+    except (json.JSONDecodeError, IndexError):
+        return {}
+    return {d.get("finding"): d for d in data.get("decisions") or [] if isinstance(d, dict)}
+
+
+def history_all(
+    cwd: str, limit: int = HISTORY_COMMITS, finding: str | None = None, pol: dict[str, Any] | None = None
+) -> list[dict[str, Any]]:
+    """Every decision (not open) in this branch's history, newest first, with authority from the note.
+
+    Without a note, authority is 'commit-access' when the trailer names someone: the person had commit access.
+    """
     rc, out, _ = git(["log", f"-{limit}", "--format=%H%x00%ad%x00%B%x01", "--date=short"], cwd)
     rows: list[dict[str, Any]] = []
     if rc != 0:
@@ -111,12 +140,35 @@ def history(cwd: str, finding: str, limit: int = HISTORY_COMMITS) -> list[dict[s
         if not rec.strip() or "Gitvow-" not in rec:
             continue
         sha, date, body = rec.split("\x00", 2)
-        for t in parse_trailers(body):
-            if t["finding"] == finding and t["answer"] != "open":
-                rows.append({**t, "sha": sha[:7], "date": date})
+        ts = [t for t in parse_trailers(body) if t["answer"] != "open" and (finding is None or t["finding"] == finding)]
+        if not ts:
+            continue
+        notes = _note_decisions(cwd, sha, body)
+        for t in ts:
+            n = notes.get(t["finding"]) or {}
+            if n.get("authority"):
+                auth = n["authority"]
+            elif not t.get("by"):
+                auth = "none"
+            else:
+                auth = authority(pol or {}, t["by"], "", "")
+            rows.append(
+                {
+                    **t,
+                    "sha": sha[:7],
+                    "date": date,
+                    "authority": auth,
+                    "kind": n.get("kind"),
+                }
+            )
     return rows
 
 
+def history(cwd: str, finding: str, limit: int = HISTORY_COMMITS) -> list[dict[str, Any]]:
+    """Earlier decisions on the same finding in this branch's history, newest first."""
+    return history_all(cwd, limit, finding)
+
+
 def proposal(hist: list[dict[str, Any]]) -> tuple[str | None, str]:
     """(proposed answer or None, sentence about the record)."""
     if not hist:
@@ -138,7 +190,26 @@ def proposal(hist: list[dict[str, Any]]) -> tuple[str | None, str]:
     return None, sentence + " Mixed record; no proposal."
 
 
-def card(cwd: str, findings: list[dict[str, Any]] | None = None, for_agent: bool = True) -> str:
+def mark_proposals(cwd: str, pol: dict[str, Any] | None = None) -> int:
+    """Store what the record proposes on each undecided finding, so the note can say whether the answer matched."""
+    st = load_state(cwd)
+    n = 0
+    for f in st.get("findings") or []:
+        if f.get("decision") or "proposed" in f:
+            continue
+        p, _ = proposal(history(cwd, f["finding"]))
+        f["proposed"] = p
+        n += 1 if p else 0
+    save_state(cwd, st)
+    return n
+
+
+def card(
+    cwd: str,
+    findings: list[dict[str, Any]] | None = None,
+    for_agent: bool = True,
+    pol: dict[str, Any] | None = None,
+) -> str:
     """The one surface a developer meets: every open finding with its evidence and what the record proposes."""
     fs = findings if findings is not None else open_findings(cwd)
     if not fs:
@@ -169,6 +240,14 @@ def card(cwd: str, findings: list[dict[str, Any]] | None = None, for_agent: bool
         if not d:
             _, sentence = proposal(history(cwd, f["finding"]))
             lines.append(f"   record: {sentence}")
+            if pol is not None:
+                from .rules import rule_for
+
+                r = rule_for(cwd, pol, f["finding"])
+                if r:
+                    lines.append(
+                        f"   rule: {r['answer']} {r['count']} times by authorities since {r['first']}; decays {r['expires']}."
+                    )
     return "\n".join(lines) + "\n"
 
 
@@ -255,6 +334,7 @@ def note_entries(findings: list[dict[str, Any]], card_user_turns: int | None) ->
                 "note": d.get("note"),
                 "decided_at": d.get("decided_at"),
                 "human_turns_after_card": turns,
+                "proposed": f.get("proposed"),
             }
         )
     return out
@@ -271,3 +351,88 @@ def take_committed(cwd: str, head: str) -> list[dict[str, Any]] | None:
     st.pop("last_commit", None)
     save_state(cwd, st)
     return lc.get("findings") or []
+
+
+def decisions_of(cwd: str, sha: str) -> list[dict[str, Any]]:
+    """Decision trailers on one commit, numbered from 1."""
+    rc, body, _ = git(["log", "-1", "--format=%B", sha], cwd)
+    if rc != 0:
+        raise ValueError(f"no such commit: {sha}")
+    return [{"n": i, **t} for i, t in enumerate(parse_trailers(body), 1)]
+
+
+def revisit(
+    cwd: str,
+    sha: str,
+    answer: str,
+    pol: dict[str, Any],
+    which: str | None = None,
+    scope: str | None = None,
+    reason: str | None = None,
+    by: str | None = None,
+    rules: list[tuple[str, str]] | None = None,
+) -> tuple[str, str]:
+    """Answer a decision already on the branch again.
+
+    Writes an empty commit carrying the new answer and `Gitvow-Revisits: <sha>`; the earlier trailer stays
+    where it was, so the record keeps both.
+    """
+    if answer not in ("accept", "decline"):
+        raise ValueError("answer must be accept or decline")
+    ds = decisions_of(cwd, sha)
+    if not ds:
+        raise ValueError(f"{sha[:7]} carries no decision trailers")
+    if which is None:
+        if len(ds) > 1:
+            listing = "\n".join(f"  {d['n']}. {d['answer']}: {d['finding']}" for d in ds)
+            raise ValueError("several decisions on this commit; pass --finding <n>:\n" + listing)
+        target = ds[0]
+    else:
+        try:
+            target = ds[int(which) - 1]
+        except (ValueError, IndexError) as e:
+            raise ValueError(f"no decision {which} on {sha[:7]}") from e
+    ident, _email, _name = identity(cwd, by)
+    note = redact(reason, rules)[:200] if reason and rules is not None else (reason or None)
+    f = {
+        "finding": target["finding"],
+        "decision": {
+            "answer": "accepted" if answer == "accept" else "declined",
+            "by": ident,
+            "scope": (scope or "").strip() or None,
+            "note": note,
+        },
+    }
+    _, full, _ = git(["rev-parse", sha], cwd)
+    msg = (
+        f"gitvow: revisit decision on {full[:7]}\n\n"
+        f"Was: {target['answer']} ({target['finding']}). Now: {f['decision']['answer']} by {ident}.\n\n"
+        f"Gitvow-Revisits: {full}\n{trailer_line(f)}\n"
+    )
+    rc, _, err = git(["-c", "core.hooksPath=/dev/null", "commit", "-q", "--allow-empty", "-m", msg], cwd)
+    if rc != 0:
+        raise ValueError(err or "commit failed")
+    _, head, _ = git(["rev-parse", "HEAD"], cwd)
+    return head, trailer_line(f) + f" (revisits {full[:7]})"
+
+
+def open_debt(cwd: str, limit: int = HISTORY_COMMITS) -> list[dict[str, Any]]:
+    """Gitvow-Open findings on the branch that no later revisit has answered."""
+    rc, out, _ = git(["log", f"-{limit}", "--format=%H%x00%ad%x00%B%x01", "--date=short"], cwd)
+    if rc != 0:
+        return []
+    revisited: set[tuple[str, str]] = set()
+    opens: list[dict[str, Any]] = []
+    for rec in out.split("\x01"):
+        rec = rec.strip("\n")
+        if not rec.strip() or "Gitvow-" not in rec:
+            continue
+        sha, date, body = rec.split("\x00", 2)
+        m = REVISITS_RE.search(body)
+        if m:
+            for t in parse_trailers(body):
+                revisited.add((m.group(1)[:7], t["finding"]))
+        for t in parse_trailers(body):
+            if t["answer"] == "open":
+                opens.append({"sha": sha[:7], "date": date, "finding": t["finding"]})
+    return [o for o in opens if (o["sha"], o["finding"]) not in revisited]

{gitvow-0.12.0 → gitvow-0.12.2}/src/gitvow/default_policy.json

@@ -79,7 +79,9 @@
     "mode": "open",
     "authorities": [],
     "production_branches": ["main", "master", "production"],
-    "_doc": "mode: open (a person's commit records Gitvow-Open for undecided findings) or strict (pre-commit refuses until gitvow decide). authorities: emails, email local parts or names whose decisions count; empty means anyone with commit access."
+    "rule_threshold": 3,
+    "rule_decay_days": 90,
+    "_doc": "rule_threshold: consistent answers by authorities before a finding becomes an earned rule; rule_decay_days: days without a new confirmation before it lapses. mode: open (a person's commit records Gitvow-Open for undecided findings) or strict (pre-commit refuses until gitvow decide). authorities: emails, email local parts or names whose decisions count; empty means anyone with commit access."
   },
   "llm_classifier": {
     "enabled": false,

{gitvow-0.12.0 → gitvow-0.12.2}/src/gitvow/digest.py

@@ -9,6 +9,7 @@ import re
 import time
 from typing import Any
 
+from . import decisions as dec
 from .recall import _commits, _plan
 from .state import toplevel
 
@@ -77,6 +78,12 @@ def build(cwd: str, since: str = "7d") -> dict[str, Any]:
                 file_sessions[f["path"]].add(r["session"])
     gate: collections.Counter[str] = collections.Counter()
     reasons: collections.Counter[str] = collections.Counter()
+    now: collections.Counter[str] = collections.Counter()  # this period's cards, findings, restores, sessions
+    before: collections.Counter[str] = collections.Counter()  # the period of the same length before it
+    span_days = max((time.mktime(time.strptime(time.strftime("%Y-%m-%d"), "%Y-%m-%d")) - _day_ts(since_day)) / 86400, 1)
+    prev_day = time.strftime("%Y-%m-%d", time.localtime(_day_ts(since_day) - span_days * 86400))
+    sess_now: set[str] = set()
+    sess_before: set[str] = set()
     log = os.path.join(top, ".git", "gitvow-hooks.log")
     if os.path.exists(log):
         with open(log) as fh:
@@ -85,11 +92,34 @@ def build(cwd: str, since: str = "7d") -> dict[str, Any]:
                     e = json.loads(ln)
                 except json.JSONDecodeError:
                     continue
-                if (e.get("ts") or "")[:10] < since_day:
+                day = (e.get("ts") or "")[:10]
+                if day < prev_day:
                     continue
-                if e.get("kind") in ("blocked", "confirm_required"):
-                    gate[e["kind"]] += 1
+                bucket, sset = (now, sess_now) if day >= since_day else (before, sess_before)
+                kind = e.get("kind")
+                if kind == "session_start" and e.get("session_id"):
+                    sset.add(e["session_id"])
+                elif kind == "card":
+                    bucket["cards"] += 1
+                    bucket["pre_answered"] += int(e.get("proposed") or 0)
+                elif kind == "finding":
+                    bucket["findings"] += int(e.get("new") or 0)
+                elif kind == "restore":
+                    bucket["restores"] += 1
+                if day < since_day:
+                    continue
+                if kind in ("blocked", "confirm_required"):
+                    gate[kind] += 1
                     reasons[e.get("reason") or "?"] += 1
+    decided = _decisions_in_period(top, since_day)
+    debt = dec.open_debt(top)
+    from .policy import PolicyError, load_policy
+    from .rules import derive
+
+    try:
+        rules_in_force: int | None = len(derive(top, load_policy(top))["rules"])
+    except PolicyError:
+        rules_in_force = None  # the digest renders without a valid policy
     sess_list = sorted(sessions.values(), key=lambda s: s["date"], reverse=True)
     total_cost = 0.0
     in_tok = out_tok = 0
@@ -125,9 +155,63 @@ def build(cwd: str, since: str = "7d") -> dict[str, Any]:
         },
         "files": [{"path": p, "commits": n, "sessions": len(file_sessions[p])} for p, n in files.most_common(10)],
         "human": [{"short": r["short"], "date": r["date"], "subject": r["subject"]} for r in human[:15]],
+        "decisions": {
+            **decided,
+            "debt": len(debt),
+            "debt_items": debt[:10],
+            "rules_in_force": rules_in_force,
+        },
+        "questions": {
+            "cards": now["cards"],
+            "sessions": len(sess_now) or len(sessions),
+            "per_session": round(now["cards"] / (len(sess_now) or len(sessions)), 2)
+            if (sess_now or sessions)
+            else None,
+            "per_session_before": round(before["cards"] / len(sess_before), 2) if sess_before else None,
+            "findings": now["findings"],
+            "immediate": gate["confirm_required"],
+        },
+        "payback": {
+            "snapshots_restored": now["restores"],
+            "pre_answered": now["pre_answered"],
+            "answers_matching_proposal": decided["matched_proposal"],
+        },
     }
 
 
+def _day_ts(day: str) -> float:
+    try:
+        return time.mktime(time.strptime(day, "%Y-%m-%d"))
+    except ValueError:
+        return time.time()
+
+
+def _decisions_in_period(top: str, since_day: str) -> dict[str, int]:
+    """Accepted, declined, open and revisited trailers on commits in the period; answers that matched the proposal."""
+    from .state import git
+
+    rc, out, _ = git(["log", "-5000", f"--since={since_day}", "--format=%H%x00%B%x01"], top)
+    c: collections.Counter[str] = collections.Counter()
+    if rc != 0:
+        return {"accepted": 0, "declined": 0, "open": 0, "revisited": 0, "matched_proposal": 0}
+    for rec in out.split("\x01"):
+        rec = rec.strip("\n")
+        if not rec.strip() or "Gitvow-" not in rec:
+            continue
+        sha, body = rec.split("\x00", 1)
+        if dec.REVISITS_RE.search(body):
+            c["revisited"] += 1
+        ts = dec.parse_trailers(body)
+        for t in ts:
+            c[t["answer"]] += 1
+        if any(t["answer"] != "open" for t in ts):
+            for n in dec._note_decisions(top, sha, body).values():
+                wanted = {"accept": "accepted", "decline": "declined"}.get(n.get("proposed") or "")
+                if wanted and wanted == n.get("answer"):
+                    c["matched_proposal"] += 1
+    return {k: c[k] for k in ("accepted", "declined", "open", "revisited", "matched_proposal")}
+
+
 def render(d: dict[str, Any]) -> str:
     pct = f" ({100 * d['agent_commits'] // d['commits']}%)" if d["commits"] else ""
     out = [f"## gitvow digest · {d['repo']} · {d['since']} → {d['until']}", ""]
@@ -151,6 +235,33 @@ def render(d: dict[str, Any]) -> str:
         out.append(
             f"Cost: ${c['estimated_usd']:.2f} estimated · {c['input_tokens'] / 1e6:.1f}M input, {c['output_tokens'] / 1e6:.1f}M output tokens{unp}"
         )
+    ds, q, pb = d.get("decisions") or {}, d.get("questions") or {}, d.get("payback") or {}
+    if ds:
+        line = f"Decisions: {ds['accepted']} accepted · {ds['declined']} declined · {ds['open']} open"
+        if ds.get("debt"):
+            line += f" · decision debt {ds['debt']} (open findings nobody has answered)"
+        if ds.get("revisited"):
+            line += f" · {ds['revisited']} revisited"
+        if ds.get("rules_in_force") is not None:
+            line += f" · earned rules in force {ds['rules_in_force']}"
+        out.append(line)
+    if q:
+        per = "n/a" if q.get("per_session") is None else f"{q['per_session']:.2f}"
+        was = f", was {q['per_session_before']:.2f}" if q.get("per_session_before") is not None else ""
+        out.append(
+            f"Questions: {q['cards']} card{'s' if q['cards'] != 1 else ''} over {q['sessions']} session{'s' if q['sessions'] != 1 else ''} "
+            f"({per} per session{was}) · {q['findings']} findings collected · {q['immediate']} immediate confirmation{'s' if q['immediate'] != 1 else ''}"
+        )
+    if pb and any(pb.values()):
+        out.append(
+            f"Payback: {pb['snapshots_restored']} snapshot{'s' if pb['snapshots_restored'] != 1 else ''} restored · "
+            f"{pb['pre_answered']} question{'s' if pb['pre_answered'] != 1 else ''} pre-answered by the record · "
+            f"{pb['answers_matching_proposal']} answer{'s' if pb['answers_matching_proposal'] != 1 else ''} matched the proposal"
+        )
+    if ds.get("debt_items"):
+        out += ["", "### Decision debt"]
+        for o in ds["debt_items"]:
+            out.append(f"{o['sha']}  {o['date'][5:]}  {o['finding']}  · gitvow revisit {o['sha']} accept|decline")
     if d["sessions"]:
         out += ["", "### Sessions"]
         for s in d["sessions"]:

{gitvow-0.12.0 → gitvow-0.12.2}/src/gitvow/hooks/__init__.py

@@ -47,7 +47,20 @@ def session_start(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
     st.pop("pending_commit", None)
     save_state(cwd, st)
     log_event(cwd, "session_start", {"session_id": h.get("session_id")})
-    return 0, ""
+    return 0, _rules_context(cwd, home)
+
+
+def _rules_context(cwd: str, home: str | None) -> str:
+    """Earned rules as context for the agent; SessionStart stdout reaches the conversation."""
+    from ..rules import derive, render
+
+    try:
+        pol = load_policy(cwd, home)
+    except PolicyError:
+        return ""
+    if not toplevel(cwd):
+        return ""
+    return render(derive(cwd, pol))
 
 
 def _policy_or_empty(cwd: str, home: str | None) -> dict[str, Any]:
@@ -118,8 +131,9 @@ def pre_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]:
                 ]
                 st["card_shown_at"] = time.strftime("%Y-%m-%dT%H:%M:%S")
                 save_state(cwd, st)
-            log_event(cwd, "card", {"findings": len(pending), "session_id": h.get("session_id")})
-            return 2, dec.card(cwd)
+            proposed = dec.mark_proposals(cwd, pol)
+            log_event(cwd, "card", {"findings": len(pending), "proposed": proposed, "session_id": h.get("session_id")})
+            return 2, dec.card(cwd, pol=pol)
         st = load_state(cwd)
         st["session_id"] = h.get("session_id") or st.get("session_id")
         st["transcript_path"] = h.get("transcript_path") or st.get("transcript_path")

{gitvow-0.12.0 → gitvow-0.12.2}/src/gitvow/policy.py

@@ -79,6 +79,10 @@ def _validate(pol: dict[str, Any], path: str) -> None:
     for key in ("authorities", "production_branches"):
         if not isinstance(dec.get(key, []), list):
             raise PolicyError(f"{path}: decisions.{key} must be a list")
+    for key in ("rule_threshold", "rule_decay_days"):
+        v = dec.get(key, 1)
+        if not isinstance(v, int) or isinstance(v, bool) or v < 1:
+            raise PolicyError(f"{path}: decisions.{key} must be a positive integer")
     for key in ("mcp_allow", "mcp_deny"):
         for pat in pol.get(key, []):
             try:

{gitvow-0.12.0 → gitvow-0.12.2}/src/gitvow/report.py

@@ -60,6 +60,8 @@ def _decisions(
         r["authority"] = n.get("authority")
         r["evidence"] = n.get("evidence") or []
         r["human_turns_after_card"] = n.get("human_turns_after_card")
+        wanted = {"accept": "accepted", "decline": "declined"}.get(n.get("proposed") or "")
+        r["pre_answered"] = bool(wanted) and wanted == r["answer"]
         r["reopen"] = bool(
             r.get("scope")
             and tgt
@@ -135,6 +137,7 @@ def build(cwd: str, base: str, head: str = "HEAD", target: str | None = None) ->
             "declined": sum(1 for d in alld if d["answer"] == "declined"),
             "open": sum(1 for d in alld if d["answer"] == "open"),
             "reopened": sum(1 for d in alld if d.get("reopen")),
+            "pre_answered": sum(1 for d in alld if d.get("pre_answered")),
         },
         "agent_commits": len(agent),
         "human_commits": len(commits) - len(agent),
@@ -161,6 +164,8 @@ def render_markdown(r: dict[str, Any]) -> str:
             bits.append(f"**{ds['open']} open**")
         if ds.get("reopened"):
             bits.append(f"**{ds['reopened']} to reopen for {r.get('target')}**")
+        if ds.get("pre_answered"):
+            bits.append(f"{ds['pre_answered']} matched the record's proposal")
         lines += [f"**Decisions:** {' · '.join(bits)}", ""]
     for c in r["commits"]:
         if c["kind"] == "human":
@@ -213,6 +218,8 @@ def _decision_lines(ds: list[dict[str, Any]], target: str | None) -> list[str]:
         scope = f", scope {d['scope']}" if d.get("scope") else ""
         note = f": {d['note']}" if d.get("note") else ""
         line = f"**{d['answer'].capitalize()}:** {d['finding']} by {who}{auth}{scope}{note}"
+        if d.get("pre_answered"):
+            line += " · matched the record's proposal"
         if d.get("human_turns_after_card") == 0:
             line += " · **answered without a user message in the transcript**"
         if d.get("reopen"):

gitvow-0.12.2/src/gitvow/rules.py

@@ -0,0 +1,170 @@
+"""Earned rules: findings this repository has answered the same way, by people the policy names, often enough.
+
+A rule is context for the agent, not permission. The gate still asks; the card arrives with the rule attached.
+Rules carry their evidence and dates and decay when nobody has confirmed them within the window.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from typing import Any
+
+from .decisions import history_all
+from .state import toplevel
+
+DEFAULT_THRESHOLD = 3
+DEFAULT_DECAY_DAYS = 90
+START = "<!-- gitvow:rules -->"
+END = "<!-- /gitvow:rules -->"
+INSTRUCTION_FILES = {
+    "claude": "CLAUDE.md",
+    "codex": "AGENTS.md",
+    "factory": "AGENTS.md",
+    "gemini": "GEMINI.md",
+    "copilot": ".github/copilot-instructions.md",
+    "cursor": ".cursor/rules/gitvow.mdc",
+}
+
+
+def settings(pol: dict[str, Any]) -> tuple[int, int]:
+    d = pol.get("decisions") or {}
+    return int(d.get("rule_threshold") or DEFAULT_THRESHOLD), int(d.get("rule_decay_days") or DEFAULT_DECAY_DAYS)
+
+
+def derive(cwd: str, pol: dict[str, Any], today: str | None = None) -> dict[str, Any]:
+    """Rules from the branch's decision history. Only decisions by authorities count; a contradiction resets."""
+    top = toplevel(cwd) or cwd
+    threshold, decay = settings(pol)
+    today_d = _dt.date.fromisoformat(today) if today else _dt.date.today()
+    rows = history_all(top, pol=pol)  # newest first, with authority from the note when available
+    by_finding: dict[str, list[dict[str, Any]]] = {}
+    for r in rows:
+        by_finding.setdefault(r["finding"], []).append(r)
+    rules, candidates, decayed = [], [], []
+    for finding, hist in by_finding.items():
+        auth = [h for h in hist if h.get("authority") in ("policy", "commit-access")]
+        if not auth:
+            continue
+        answer = auth[0]["answer"]
+        run = []
+        for h in auth:  # newest first: count the unbroken run of the latest answer
+            if h["answer"] != answer:
+                break
+            run.append(h)
+        dates = sorted(h["date"] for h in run)  # history order is not date order once commits are rebased or backdated
+        last = _dt.date.fromisoformat(dates[-1])
+        expires = last + _dt.timedelta(days=decay)
+        entry = {
+            "finding": finding,
+            "kind": run[0].get("kind") or _kind(finding),
+            "answer": answer,
+            "count": len(run),
+            "threshold": threshold,
+            "first": dates[0],
+            "last": dates[-1],
+            "by": sorted({h["by"] for h in run if h.get("by")}),
+            "scopes": sorted({h["scope"] for h in run if h.get("scope")}),
+            "commits": [h["sha"] for h in run[:5]],
+            "expires": expires.isoformat(),
+            "contradicted_by": len(auth) - len(run),
+        }
+        if len(run) < threshold:
+            candidates.append(entry)
+        elif expires < today_d:
+            decayed.append(entry)
+        else:
+            rules.append(entry)
+    key = lambda e: (e["last"], e["count"])  # noqa: E731
+    return {
+        "repo": top,
+        "threshold": threshold,
+        "decay_days": decay,
+        "rules": sorted(rules, key=key, reverse=True),
+        "candidates": sorted(candidates, key=key, reverse=True),
+        "decayed": sorted(decayed, key=key, reverse=True),
+    }
+
+
+def _kind(finding: str) -> str:
+    if finding.startswith("remove route "):
+        return "route-removal"
+    if finding.startswith("route "):
+        return "route"
+    if finding.startswith("run "):
+        return "command"
+    return "edit"
+
+
+def rule_for(cwd: str, pol: dict[str, Any], finding: str) -> dict[str, Any] | None:
+    for r in derive(cwd, pol)["rules"]:
+        if r["finding"] == finding:
+            return r
+    return None
+
+
+def _sentence(r: dict[str, Any]) -> str:
+    who = ", ".join(r["by"][:3]) or "authorities"
+    scope = f" for {', '.join(r['scopes'])}" if r["scopes"] else ""
+    times = f"{r['count']} time{'s' if r['count'] != 1 else ''}"
+    if r["answer"] == "accepted":
+        return (
+            f"`{r['finding']}` has been accepted {times}{scope} ({r['first']} to {r['last']}, by {who}). "
+            "Expect the card to propose accept; still put it to the person."
+        )
+    return (
+        f"`{r['finding']}` has been declined {times} ({r['first']} to {r['last']}, by {who}). "
+        "Propose the alternative first; if the change still needs it, say why on the card."
+    )
+
+
+def render(d: dict[str, Any], for_agent: bool = True) -> str:
+    """Markdown block for an instruction file or SessionStart context."""
+    if not d["rules"]:
+        return ""
+    lines = [
+        START,
+        f"## What this repository has decided ({len(d['rules'])} earned rule{'s' if len(d['rules']) != 1 else ''})",
+        "",
+        "Derived by gitvow from decisions on earlier commits. Context, not permission: the gate still asks at commit.",
+        "",
+    ]
+    for r in d["rules"]:
+        lines.append(f"- {_sentence(r)} Decays {r['expires']} unless confirmed again.")
+    if not for_agent and d["candidates"]:
+        lines += ["", f"Not yet rules (fewer than {d['threshold']} consistent answers by authorities):"]
+        for r in d["candidates"]:
+            lines.append(
+                f"- {r['finding']}: {r['answer']} {r['count']} times (last {r['last']} by {', '.join(r['by'])})"
+            )
+    if not for_agent and d["decayed"]:
+        lines += ["", "Decayed (no confirmation within the window):"]
+        for r in d["decayed"]:
+            lines.append(
+                f"- {r['finding']}: {r['answer']} {r['count']} times, last {r['last']}, expired {r['expires']}"
+            )
+    lines.append(END)
+    return "\n".join(lines) + "\n"
+
+
+def write_section(path: str, block: str) -> str:
+    """Replace or append the managed section in an instruction file; remove it when the block is empty."""
+    import os
+
+    existing = ""
+    if os.path.exists(path):
+        with open(path) as fh:
+            existing = fh.read()
+    pat = re.compile(re.escape(START) + r".*?" + re.escape(END) + r"\n?", re.S)
+    if pat.search(existing):
+        new = pat.sub(lambda m: block, existing)
+        action = "updated" if block else "removed"
+    elif block:
+        new = (existing.rstrip("\n") + "\n\n" if existing.strip() else "") + block
+        action = "added"
+    else:
+        return "nothing to write"
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    with open(path, "w") as fh:
+        fh.write(new)
+    return f"{action} managed section in {path}"

{gitvow-0.12.0 → gitvow-0.12.2}/src/gitvow/snapshots.py

@@ -169,6 +169,7 @@ def restore(cwd: str, ref: str, to: str | None = None) -> tuple[int, str]:
     rc, _, err = git(["worktree", "add", "--detach", to, ref], top)
     if rc != 0:
         return 1, err
+    log_event(top, "restore", {"ref": ref, "to": to})
     return 0, to
 
 

{gitvow-0.12.0 → gitvow-0.12.2/src/gitvow.egg-info}/PKG-INFO

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

@@ -16,6 +16,7 @@ src/gitvow/providers.py
 src/gitvow/recall.py
 src/gitvow/redact.py
 src/gitvow/report.py
+src/gitvow/rules.py
 src/gitvow/selftest.py
 src/gitvow/snapshots.py
 src/gitvow/state.py
@@ -41,5 +42,6 @@ tests/test_providers.py
 tests/test_recall.py
 tests/test_redact.py
 tests/test_report.py
+tests/test_rules.py
 tests/test_snapshots.py
 tests/test_transcript_formats.py

{gitvow-0.12.0 → gitvow-0.12.2}/tests/test_decisions.py

@@ -160,7 +160,7 @@ def test_report_lists_decisions_reopens_scope_and_summarises(repo, home, payload
     (repo / "a.txt").write_text("y\n")
     git(repo, "commit", "-qam", "human commit")  # Gitvow-Open
     r = build(str(repo), base, "HEAD", target="main")
-    assert r["decisions"] == {"accepted": 1, "declined": 0, "open": 1, "reopened": 1}
+    assert r["decisions"] == {"accepted": 1, "declined": 0, "open": 1, "reopened": 1, "pre_answered": 0}
     md = render_markdown(r)
     assert "**Decisions:** 1 accepted · 0 declined · **1 open** · **1 to reopen for main**" in md
     assert "accepted for staging; this pull request targets main. Accept for main?" in md
@@ -174,3 +174,50 @@ def test_report_lists_decisions_reopens_scope_and_summarises(repo, home, payload
     monkeypatch.chdir(repo)
     assert cli.main(["report", "--base", base, "--decisions-summary"]) == 0
     assert capsys.readouterr().out == summary
+
+
+def test_proposal_recorded_and_revisit_keeps_both(repo, home, payload, transcript, monkeypatch, capsys):
+    f = "edit core/authz_rules.go"
+    (repo / "a.txt").write_text("p\n")
+    git(repo, "commit", "-qam", f"prior\n\nGitvow-Accepted: {f} by nikhil")
+    session_start(payload("SessionStart"), str(home))
+    pre_tool_use(payload("PreToolUse", "Edit", {"file_path": "core/authz_rules.go"}, transcript), str(home))
+    code, msg = pre_tool_use(payload("PreToolUse", "Bash", {"command": "git commit -m x"}, transcript), str(home))
+    assert code == 2 and "Proposed: accept." in msg
+    st = json.loads((repo / ".git" / "gitvow-session.json").read_text())
+    assert st["findings"][0]["proposed"] == "accept"
+    assert '"kind": "card", "findings": 1, "proposed": 1' in (repo / ".git" / "gitvow-hooks.log").read_text()
+    dec.decide(str(repo), "1", "accept", {}, user_turns=2)
+    pre_tool_use(payload("PreToolUse", "Bash", {"command": "git commit -m x"}, transcript), str(home))
+    _install_hooks(repo)
+    (repo / "a.txt").write_text("q\n")
+    git(repo, "commit", "-qam", "agent")
+    post_tool_use(payload("PostToolUse", "Bash", {"command": "git commit -m x"}, transcript), str(home))
+    note = json.loads(git(repo, "notes", "--ref=gitvow/sess-1", "show", "HEAD").split("\n", 1)[1])
+    assert note["decisions"][0]["proposed"] == "accept"
+    base = git(repo, "rev-parse", "HEAD~1")
+    r = build(str(repo), base, "HEAD")
+    assert r["decisions"]["pre_answered"] == 1 and "matched the record's proposal" in render_markdown(r)
+    # a human commit leaves an open finding; revisit closes the debt and keeps the earlier trailer
+    pre_tool_use(payload("PreToolUse", "Edit", {"file_path": ".github/workflows/ci.yml"}), str(home))
+    (repo / "a.txt").write_text("r\n")
+    git(repo, "commit", "-qam", "human")
+    open_sha = git(repo, "rev-parse", "--short", "HEAD")
+    assert dec.open_debt(str(repo)) == [
+        {"sha": open_sha, "date": dec.open_debt(str(repo))[0]["date"], "finding": "edit .github/workflows/ci.yml"}
+    ]
+    monkeypatch.chdir(repo)
+    assert cli.main(["revisit", open_sha]) == 0
+    assert "1. open: edit .github/workflows/ci.yml" in capsys.readouterr().out
+    assert cli.main(["revisit", open_sha, "accept", "--reason", "seen it"]) == 0
+    out = capsys.readouterr().out
+    assert out.strip() == f"Gitvow-Accepted: edit .github/workflows/ci.yml by t: seen it (revisits {open_sha})"
+    body = git(repo, "log", "-1", "--format=%B")
+    assert f"Gitvow-Revisits: {git(repo, 'rev-parse', open_sha)}" in body and "Was: open" in body
+    assert "Gitvow-Open: edit .github/workflows/ci.yml" in git(repo, "log", "-1", "--format=%B", open_sha)
+    assert dec.open_debt(str(repo)) == []
+    assert git(repo, "diff", "HEAD~1", "HEAD") == ""  # an empty commit
+    assert cli.main(["revisit", "HEAD", "decline", "--finding", "9"]) == 1
+    assert "no decision 9" in capsys.readouterr().err
+    # history now counts the revisit as the latest answer on that finding
+    assert dec.history(str(repo), "edit .github/workflows/ci.yml")[0]["answer"] == "accepted"

{gitvow-0.12.0 → gitvow-0.12.2}/tests/test_digest.py

@@ -60,3 +60,45 @@ def test_digest_counts_and_render(repo, home, payload, transcript, monkeypatch,
     assert "### Human commits in the period" in out and "human only" in out
     assert cli.main(["digest", "--since", "2099-01-01"]) == 0
     assert "Commits: 0" in capsys.readouterr().out
+
+
+def test_digest_decisions_questions_and_payback(repo, home, payload, transcript, monkeypatch, capsys):
+    from gitvow import decisions as dec
+    from gitvow.digest import build, render
+    from gitvow.hooks import post_tool_use, pre_tool_use, session_start
+    from gitvow.install import _write_git_hook
+    from gitvow.state import log_event
+
+    session_start(payload("SessionStart"), str(home))
+    pre_tool_use(payload("PreToolUse", "Edit", {"file_path": "core/authz_rules.go"}, transcript), str(home))
+    assert pre_tool_use(payload("PreToolUse", "Bash", {"command": "git commit -m x"}, transcript), str(home))[0] == 2
+    dec.decide(str(repo), "1", "accept", {}, user_turns=2)
+    pre_tool_use(payload("PreToolUse", "Bash", {"command": "git commit -m x"}, transcript), str(home))
+    _write_git_hook(str(repo / ".gitvow" / "git-hooks"))
+    git(repo, "config", "core.hooksPath", ".gitvow/git-hooks")
+    (repo / "a.txt").write_text("x\n")
+    git(repo, "commit", "-qam", "agent")
+    post_tool_use(payload("PostToolUse", "Bash", {"command": "git commit -m x"}, transcript), str(home))
+    pre_tool_use(payload("PreToolUse", "Edit", {"file_path": ".github/workflows/ci.yml"}), str(home))
+    (repo / "a.txt").write_text("y\n")
+    git(repo, "commit", "-qam", "human")
+    log_event(str(repo), "restore", {"ref": "refs/gitvow/snapshots/sess-1/1"})
+    pre_tool_use(payload("PreToolUse", "Bash", {"command": "git push origin main"}), str(home))  # immediate
+    d = build(str(repo), "1d")
+    assert d["decisions"]["accepted"] == 1 and d["decisions"]["open"] == 1 and d["decisions"]["debt"] == 1
+    assert (
+        d["decisions"]["rules_in_force"] == 0
+        and d["decisions"]["debt_items"][0]["finding"] == "edit .github/workflows/ci.yml"
+    )
+    assert d["questions"]["cards"] == 1 and d["questions"]["sessions"] == 1 and d["questions"]["per_session"] == 1.0
+    assert d["questions"]["findings"] == 2 and d["questions"]["immediate"] == 1
+    assert d["payback"] == {"snapshots_restored": 1, "pre_answered": 0, "answers_matching_proposal": 0}
+    text = render(d)
+    assert "Decisions: 1 accepted · 0 declined · 1 open · decision debt 1" in text
+    assert (
+        "Questions: 1 card over 1 session (1.00 per session) · 2 findings collected · 1 immediate confirmation" in text
+    )
+    assert (
+        "Payback: 1 snapshot restored · 0 questions pre-answered by the record · 0 answers matched the proposal" in text
+    )
+    assert "### Decision debt" in text and "gitvow revisit" in text

gitvow-0.12.2/tests/test_rules.py

@@ -0,0 +1,131 @@
+import json
+from pathlib import Path
+
+from gitvow import cli
+from gitvow import decisions as dec
+from gitvow.hooks import pre_tool_use, session_start
+from gitvow.policy import DEFAULT_POLICY_PATH
+from gitvow.rules import END, START, derive, render, write_section
+
+
+def _decided_commit(repo, subject, trailer, date="2026-09-01T12:00:00"):
+    (repo / "a.txt").write_text(subject + "\n")
+    import subprocess
+
+    subprocess.run(
+        ["git", "commit", "-qam", f"{subject}\n\n{trailer}"],
+        cwd=repo,
+        env={**__import__("os").environ, "GIT_AUTHOR_DATE": date, "GIT_COMMITTER_DATE": date},
+        check=True,
+    )
+
+
+def _pol():
+    return json.loads(Path(DEFAULT_POLICY_PATH).read_text())
+
+
+def test_rules_need_threshold_authority_and_recency(repo):
+    pol = _pol()
+    f = "edit core/authz_rules.go"
+    _decided_commit(repo, "c1", f"Gitvow-Accepted: {f} by nikhil scope=staging", "2026-06-01T12:00:00")
+    _decided_commit(repo, "c2", f"Gitvow-Accepted: {f} by nikhil", "2026-06-10T12:00:00")
+    d = derive(str(repo), pol, today="2026-06-20")
+    assert d["rules"] == [] and d["candidates"][0]["count"] == 2 and d["candidates"][0]["answer"] == "accepted"
+    _decided_commit(repo, "c3", f"Gitvow-Accepted: {f} by priya", "2026-06-15T12:00:00")
+    d = derive(str(repo), pol, today="2026-06-20")
+    r = d["rules"][0]
+    assert r["count"] == 3 and r["by"] == ["nikhil", "priya"] and r["scopes"] == ["staging"]
+    assert r["first"] == "2026-06-01" and r["last"] == "2026-06-15" and r["expires"] == "2026-09-13"
+    # decayed after the window
+    d = derive(str(repo), pol, today="2026-09-20")
+    assert d["rules"] == [] and d["decayed"][0]["finding"] == f
+    # a contradiction resets the run
+    _decided_commit(repo, "c4", f"Gitvow-Declined: {f} by nikhil: not any more", "2026-06-16T12:00:00")
+    d = derive(str(repo), pol, today="2026-06-20")
+    assert (
+        d["rules"] == [] and d["candidates"][0]["answer"] == "declined" and d["candidates"][0]["contradicted_by"] == 3
+    )
+    # only authorities count once the policy names them
+    pol["decisions"]["authorities"] = ["security@example.com"]
+    _decided_commit(repo, "c5", f"Gitvow-Declined: {f} by security", "2026-06-17T12:00:00")
+    _decided_commit(repo, "c6", f"Gitvow-Declined: {f} by security", "2026-06-18T12:00:00")
+    d = derive(str(repo), pol, today="2026-06-20")
+    assert d["rules"] == [] and d["candidates"][0]["count"] == 2  # nikhil's decline is data, not a rule
+    pol["decisions"]["rule_threshold"] = 2
+    assert derive(str(repo), pol, today="2026-06-20")["rules"][0]["answer"] == "declined"
+
+
+def test_render_and_managed_section(tmp_path):
+    d = {
+        "threshold": 3,
+        "decay_days": 90,
+        "rules": [
+            {
+                "finding": "route /v1/x in api.py",
+                "answer": "declined",
+                "count": 4,
+                "first": "2026-05-01",
+                "last": "2026-06-01",
+                "by": ["nikhil"],
+                "scopes": [],
+                "expires": "2026-08-30",
+            }
+        ],
+        "candidates": [{"finding": "edit ci.yml", "answer": "accepted", "count": 1, "last": "2026-06-02", "by": ["t"]}],
+        "decayed": [],
+    }
+    block = render(d)
+    assert block.startswith(START) and block.rstrip().endswith(END)
+    assert (
+        "has been declined 4 times" in block
+        and "Propose the alternative first" in block
+        and "Decays 2026-08-30" in block
+    )
+    assert "Not yet rules" not in block and "Not yet rules" in render(d, for_agent=False)
+    p = tmp_path / "CLAUDE.md"
+    p.write_text("# Project\n\nRead me.\n")
+    assert write_section(str(p), block).startswith("added")
+    assert p.read_text().startswith("# Project\n\nRead me.\n\n" + START)
+    d["rules"][0]["count"] = 5
+    assert write_section(str(p), render(d)).startswith("updated")
+    assert p.read_text().count(START) == 1 and "declined 5 times" in p.read_text()
+    assert write_section(str(p), "").startswith("removed")
+    assert START not in p.read_text() and p.read_text().startswith("# Project")
+    assert render({"rules": [], "candidates": [], "decayed": [], "threshold": 3, "decay_days": 90}) == ""
+
+
+def test_card_and_session_start_carry_the_rule(repo, home, payload, monkeypatch, capsys):
+    f = "edit core/authz_rules.go"
+    for i in range(3):
+        _decided_commit(repo, f"c{i}", f"Gitvow-Accepted: {f} by nikhil", f"2026-09-0{i + 1}T12:00:00")
+    code, msg = session_start(payload("SessionStart"), str(home))
+    assert code == 0 and START in msg and "accepted 3 times" in msg
+    pre_tool_use(payload("PreToolUse", "Edit", {"file_path": "core/authz_rules.go"}), str(home))
+    code, msg = pre_tool_use(payload("PreToolUse", "Bash", {"command": "git commit -m x"}), str(home))
+    assert code == 2 and "rule: accepted 3 times by authorities since 2026-09-01; decays 2026-12-02." in msg
+    assert "Proposed: accept." in msg
+    monkeypatch.chdir(repo)
+    assert cli.main(["rules"]) == 0
+    assert "earned rule" in capsys.readouterr().out
+    assert cli.main(["rules", "--write"]) == 0
+    assert "added managed section" in capsys.readouterr().out and START in (repo / "CLAUDE.md").read_text()
+    assert cli.main(["rules", "--write", "--agent", "codex"]) == 0
+    assert START in (repo / "AGENTS.md").read_text()
+    capsys.readouterr()
+    assert cli.main(["rules", "--json"]) == 0
+    assert json.loads(capsys.readouterr().out)["rules"][0]["count"] == 3
+    # the hook command prints SessionStart context on stdout for Claude Code
+    import io
+    import sys
+
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload("SessionStart"))))
+    assert cli.main(["hook", "SessionStart"]) == 0
+    out = capsys.readouterr().out
+    assert START in out and "still put it to the person" in out
+
+
+def test_no_rules_message(repo, home, monkeypatch, capsys):
+    monkeypatch.chdir(repo)
+    assert cli.main(["rules"]) == 0
+    assert "no earned rules yet" in capsys.readouterr().out
+    assert dec.history_all(str(repo)) == []