gitvow 0.29.2__tar.gz → 0.31.0__tar.gz

{gitvow-0.29.2/src/gitvow.egg-info → gitvow-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.29.2
+Version: 0.31.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
@@ -93,7 +93,7 @@ The docs site is the source of truth: **https://wirevow.dev/gitvow** (built from
 
 - [Quick start](docs/quickstart.md)
 - Concepts: [Sessions, steps and notes](docs/concepts/sessions.md) · [The gate](docs/concepts/gate.md) · [What stays out of git](docs/concepts/storage.md)
-- Guides: [Install per user or per repo](docs/guides/install.md) · [Write a policy](docs/guides/policy.md) · [Read a commit's session](docs/guides/reading.md) · [Run a trial](docs/guides/trial.md) · [Redaction](docs/guides/redaction.md)
+- Guides: [Install per user or per repo](docs/guides/install.md) · [Write a policy](docs/guides/policy.md) · [Read a commit's session](docs/guides/reading.md) · [Answer the card](docs/guides/decisions.md) · [State the intent](docs/guides/intent.md) · [Did the decision hold?](docs/guides/outcomes.md) · [Run a trial](docs/guides/trial.md) · [Redaction](docs/guides/redaction.md)
 - Reference: [CLI](docs/reference/cli.md) · [Hook payloads](docs/reference/hooks.md) · [Note schema](docs/reference/note.md) · [Policy schema](docs/reference/policy.md)
 - [Security](docs/security.md) · [Roadmap](docs/roadmap.md) · [FAQ](docs/faq.md)
 
@@ -102,13 +102,14 @@ The docs site is the source of truth: **https://wirevow.dev/gitvow** (built from
 ```
 Claude Code ──hook──▶ gitvow hook PreToolUse ──▶ policy ──▶ allow / confirm / deny  (exit 0 / 2 / 2)
             ──hook──▶ gitvow hook PostToolUse ─▶ on `git commit`: read transcript → redact → git notes add
-git commit ──prepare-commit-msg──▶ Gitvow-Session / Gitvow-Step trailers   (from .git/gitvow-session.json)
+Claude Code ──hook──▶ gitvow hook UserPromptSubmit ▶ first line of the first message → redact → the session's intent
+git commit ──prepare-commit-msg──▶ Gitvow-Session / Gitvow-Step / Gitvow-Intent trailers   (from .git/gitvow-session.json)
 Claude Code ──hook──▶ gitvow hook Stop ─────────▶ ~/.gitvow/ledger/<session>.json
 ```
 
 | Data | Where | Enters git? |
 |---|---|---|
-| session id, step | commit trailers | yes |
+| session id, step, intent (one redacted line in the person's words) | commit trailers | yes |
 | session note (structure, redacted plan, attribution) | `refs/notes/sessions` | as a note; local until pushed |
 | ledger, hook log, session state | `~/.gitvow/`, `<repo>/.git/` | no |
 | transcript | untouched | never |

{gitvow-0.29.2 → gitvow-0.31.0}/README.md

@@ -65,7 +65,7 @@ The docs site is the source of truth: **https://wirevow.dev/gitvow** (built from
 
 - [Quick start](docs/quickstart.md)
 - Concepts: [Sessions, steps and notes](docs/concepts/sessions.md) · [The gate](docs/concepts/gate.md) · [What stays out of git](docs/concepts/storage.md)
-- Guides: [Install per user or per repo](docs/guides/install.md) · [Write a policy](docs/guides/policy.md) · [Read a commit's session](docs/guides/reading.md) · [Run a trial](docs/guides/trial.md) · [Redaction](docs/guides/redaction.md)
+- Guides: [Install per user or per repo](docs/guides/install.md) · [Write a policy](docs/guides/policy.md) · [Read a commit's session](docs/guides/reading.md) · [Answer the card](docs/guides/decisions.md) · [State the intent](docs/guides/intent.md) · [Did the decision hold?](docs/guides/outcomes.md) · [Run a trial](docs/guides/trial.md) · [Redaction](docs/guides/redaction.md)
 - Reference: [CLI](docs/reference/cli.md) · [Hook payloads](docs/reference/hooks.md) · [Note schema](docs/reference/note.md) · [Policy schema](docs/reference/policy.md)
 - [Security](docs/security.md) · [Roadmap](docs/roadmap.md) · [FAQ](docs/faq.md)
 
@@ -74,13 +74,14 @@ The docs site is the source of truth: **https://wirevow.dev/gitvow** (built from
 ```
 Claude Code ──hook──▶ gitvow hook PreToolUse ──▶ policy ──▶ allow / confirm / deny  (exit 0 / 2 / 2)
             ──hook──▶ gitvow hook PostToolUse ─▶ on `git commit`: read transcript → redact → git notes add
-git commit ──prepare-commit-msg──▶ Gitvow-Session / Gitvow-Step trailers   (from .git/gitvow-session.json)
+Claude Code ──hook──▶ gitvow hook UserPromptSubmit ▶ first line of the first message → redact → the session's intent
+git commit ──prepare-commit-msg──▶ Gitvow-Session / Gitvow-Step / Gitvow-Intent trailers   (from .git/gitvow-session.json)
 Claude Code ──hook──▶ gitvow hook Stop ─────────▶ ~/.gitvow/ledger/<session>.json
 ```
 
 | Data | Where | Enters git? |
 |---|---|---|
-| session id, step | commit trailers | yes |
+| session id, step, intent (one redacted line in the person's words) | commit trailers | yes |
 | session note (structure, redacted plan, attribution) | `refs/notes/sessions` | as a note; local until pushed |
 | ledger, hook log, session state | `~/.gitvow/`, `<repo>/.git/` | no |
 | transcript | untouched | never |

{gitvow-0.29.2 → gitvow-0.31.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitvow"
-version = "0.29.2"
+version = "0.31.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.29.2 → gitvow-0.31.0}/src/gitvow/adapters.py

@@ -18,6 +18,7 @@ AGENTS = ("claude", "codex", "gemini", "cursor", "copilot", "factory")
 EVENT_MAP: dict[str, dict[str, str]] = {
     "claude": {
         "SessionStart": "SessionStart",
+        "UserPromptSubmit": "UserPromptSubmit",
         "PreToolUse": "PreToolUse",
         "PostToolUse": "PostToolUse",
         "Stop": "Stop",
@@ -137,6 +138,8 @@ def normalize(agent: str, event: str, payload: dict[str, Any]) -> list[tuple[str
     }
     if gv_event in ("SessionStart", "Stop"):
         return [(gv_event, base)]
+    if gv_event == "UserPromptSubmit":
+        return [(gv_event, {**base, "prompt": str(payload.get("prompt") or "")})]
     if gv_event == "Subagent":
         return [
             (

{gitvow-0.29.2 → gitvow-0.31.0}/src/gitvow/cli.py

@@ -20,7 +20,7 @@ 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
+from .state import git, toplevel
 
 
 def cmd_hook(a: argparse.Namespace) -> int:
@@ -628,6 +628,43 @@ def cmd_revisit(a: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_intent(a: argparse.Namespace) -> int:
+    """State what this session's task is for, in the person's words; or print or clear the intent recorded."""
+    from . import intent as im
+
+    cwd = os.getcwd()
+    if not toplevel(cwd):
+        print("not inside a git repository", file=sys.stderr)
+        return 2
+    if a.clear:
+        print("cleared" if im.clear(cwd) else "no intent was recorded", file=sys.stderr)
+        return 0
+    if not a.text:
+        i = im.current(cwd)
+        if a.json:
+            print(json.dumps(i, indent=1))
+            return 0
+        if not i:
+            print('no intent recorded for this session; state one with: gitvow intent "<what this task is for>"')
+            return 1
+        print(im.trailer_line(i))
+        return 0
+    try:
+        rules = load_rules(cwd, os.path.expanduser("~"))
+    except RedactionError as e:
+        print(f"redaction rules invalid: {e}", file=sys.stderr)
+        return 2
+    who, _, _ = dec.identity(cwd, a.by)
+    try:
+        i = im.record(cwd, " ".join(a.text), who, "stated", rules)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    print(im.trailer_line(i))
+    print("written as Gitvow-Intent on every commit the agent makes in this session", file=sys.stderr)
+    return 0
+
+
 def cmd_decide(a: argparse.Namespace) -> int:
     """Record a person's answer to one finding or all of them."""
     cwd = os.getcwd()
@@ -700,12 +737,20 @@ def cmd_show(a: argparse.Namespace) -> int:
     # A rule decision has no session, so its note lives on one ref of its own; try it too rather than
     # printing "(no session note)" on a commit that does carry the evidence for the rule it created.
     refs = ([notes_ref(m.group(1))] if m else []) + [RULES_NOTES_REF, CLAIMS_NOTES_REF, LEGACY_NOTES_REF]
+    found = False
     for ref in refs:
         rc, note, _ = git(["notes", f"--ref={ref}", "show", a.commit], os.getcwd())
         if rc == 0:
             print(note)
-            return 0
-    print("(no session note)")
+            found = True
+            break
+    if not found:
+        print("(no session note)")
+    from .outcomes import OUTCOMES_REF
+
+    rc, note, _ = git(["notes", f"--ref={OUTCOMES_REF}", "show", a.commit], os.getcwd())
+    if rc == 0:
+        print(note)  # the grade, appended beside the decision on its own ref (0.31)
     return 0
 
 
@@ -814,6 +859,27 @@ def cmd_handoff(a: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_outcomes(a: argparse.Namespace) -> int:
+    """Grade every decision-bearing commit by what happened to it: merged, closed, landed direct, reverted."""
+    from . import outcomes as oc
+
+    cwd = os.getcwd()
+    if not toplevel(cwd):
+        print("not inside a git repository", file=sys.stderr)
+        return 2
+    try:
+        pol = load_policy(cwd)
+    except PolicyError as e:
+        print(f"policy error: {e}", file=sys.stderr)
+        return 2
+    out = oc.run(cwd, pol, since=a.since, dry_run=a.dry_run, scm=not a.no_scm, regrade=a.regrade)
+    if a.json:
+        print(json.dumps(out, indent=1))
+    else:
+        print(oc.render(out), end="")
+    return 0
+
+
 def cmd_digest(a: argparse.Namespace) -> int:
     d = dg.build(os.getcwd(), a.since)
     print(json.dumps(d, indent=1) if a.json else dg.render(d), end="\n" if a.json else "")
@@ -1065,6 +1131,15 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--by")
     s.add_argument("--to", help="with refer: who the question should go to")
     s.set_defaults(f=cmd_revisit)
+    s = sub.add_parser(
+        "intent",
+        help='what this task is for, in the person\'s words: gitvow intent "let ops export orders"; alone, prints it',
+    )
+    s.add_argument("text", nargs="*", help="the intent; omit to print the one recorded")
+    s.add_argument("--clear", action="store_true", help="drop the recorded intent")
+    s.add_argument("--by", help="whose words these are, when not the committer")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(f=cmd_intent)
     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", "refer"], help="refer: not this person's call to make")
@@ -1104,6 +1179,16 @@ def main(argv: list[str] | None = None) -> int:
     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(
+        "outcomes",
+        help="did the decisions hold? grade each decision-bearing commit by its pull request verdict, landing and reverts",
+    )
+    s.add_argument("--since", default="90d", help="window of commits to grade (default 90d)")
+    s.add_argument("--dry-run", action="store_true", help="grade and print; write no notes")
+    s.add_argument("--no-scm", action="store_true", help="do not ask the forge; verdicts from git alone")
+    s.add_argument("--regrade", action="store_true", help="grade again even where the grade was final")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(f=cmd_outcomes)
     s = sub.add_parser("digest", help="period summary: agent vs human commits, sessions, attribution, gate activity")
     s.add_argument("--since", default="7d")
     s.add_argument("--json", action="store_true")

{gitvow-0.29.2 → gitvow-0.31.0}/src/gitvow/decisions.py

@@ -299,6 +299,8 @@ def card(
             **{r["finding"]: {**r, "state": "proposal"} for r in derived["proposals"]},
             **{r["finding"]: {**r, "state": "rule"} for r in derived["rules"]},
         }
+    from .intent import card_header
+
     lines = []
     if for_agent and mode == "open":
         lines += [
@@ -321,9 +323,12 @@ def card(
             "then run the commit again.",
             "",
         ]
+    lines += card_header(st.get("intent"))
     for f in fs:
         d = f.get("decision")
         head = f"{f['n']}. {f['finding']}"
+        if f.get("intent_covered") and not d:
+            head += "   [within the stated intent]"
         if d:
             head += (
                 f"   [{d['answer']} by {d['by']}"
@@ -473,6 +478,7 @@ def note_entries(findings: list[dict[str, Any]], card_user_turns: int | None) ->
                 "decided_at": d.get("decided_at"),
                 "human_turns_after_card": turns,
                 "proposed": f.get("proposed"),
+                "intent_covered": bool(f.get("intent_covered")),
             }
         )
     return out

{gitvow-0.29.2 → gitvow-0.31.0}/src/gitvow/default_policy.json

@@ -198,6 +198,15 @@
     "commit_window_seconds": 1800,
     "_doc_commit_window": "How long after the gate sees the agent's `git commit` the git hooks still treat the commit as the agent's and write its trailers. Guards against a stale flag catching a person's later commit; too short and a harness that queues tool calls loses trailers. When a commit lands past the window, PostToolUse says so and logs commit_without_trailer."
   },
+  "intent": {
+    "from_prompt": true,
+    "ask_when_missing": true,
+    "_doc": "from_prompt: in Claude Code, the first line of the session's first message is recorded as the intent, in the person's words, redacted, at most 200 characters (source=prompt on the trailer); false records nothing until someone runs gitvow intent. ask_when_missing: the agent is told at session start to ask once, in one line, when the first message did not say what the task is for; false says nothing."
+  },
+  "outcomes": {
+    "revert_window_days": 1,
+    "_doc": "revert_window_days: a decision-bearing commit reverted within this many days of landing is graded as a decision that did not hold; a later revert is recorded and does not change the grade. The public census found agent work that gets reverted is reverted within about a day. gitvow outcomes writes the grades to refs/notes/gitvow/outcomes."
+  },
   "llm_classifier": {
     "enabled": false,
     "command": "",

{gitvow-0.29.2 → gitvow-0.31.0}/src/gitvow/digest.py

@@ -10,7 +10,7 @@ import time
 from typing import Any
 
 from . import decisions as dec
-from .recall import _commits, _plan
+from .recall import _commits, _intent, _plan
 from .state import toplevel
 
 
@@ -36,6 +36,7 @@ def build(cwd: str, since: str = "7d") -> dict[str, Any]:
     agent_added = 0.0
     files: collections.Counter[str] = collections.Counter()
     file_sessions: dict[str, set[str]] = collections.defaultdict(set)
+    covered_answers: collections.Counter[str] = collections.Counter()  # answers to findings within a stated intent
     for r in agent:
         s = sessions.setdefault(
             r["session"],
@@ -49,12 +50,17 @@ def build(cwd: str, since: str = "7d") -> dict[str, Any]:
                 "cost": None,
                 "tokens": 0,
                 "unpriced": False,
+                "intent": "",
             },
         )
         s["commits"] += 1
         s["date"] = min(s["date"], r["date"])
         note = r["note"] or {}
         s["plan"] = s["plan"] or _plan(note)
+        s["intent"] = s["intent"] or _intent(note)
+        for d in note.get("decisions") or []:
+            if d.get("intent_covered") and d.get("answer") in ("accepted", "declined"):
+                covered_answers[d["answer"]] += 1
         u = note.get("usage") or {}
         if u.get("total_tokens") and (s["cost"] is None or u["total_tokens"] >= s["tokens"]):
             s["tokens"] = u["total_tokens"]  # notes carry running totals; the latest note is the session's figure
@@ -102,6 +108,10 @@ def build(cwd: str, since: str = "7d") -> dict[str, Any]:
                 elif kind == "card":
                     bucket["cards"] += 1
                     bucket["pre_answered"] += int(e.get("proposed") or 0)
+                    if e.get("intent"):
+                        bucket["cards_with_intent"] += 1
+                        bucket["findings_with_intent"] += int(e.get("findings") or 0)
+                        bucket["intent_covered"] += int(e.get("intent_covered") or 0)
                 elif kind == "finding":
                     bucket["findings"] += int(e.get("new") or 0)
                 elif kind == "restore":
@@ -112,6 +122,9 @@ def build(cwd: str, since: str = "7d") -> dict[str, Any]:
                     gate[kind] += 1
                     reasons[e.get("reason") or "?"] += 1
     decided = _decisions_in_period(top, since_day)
+    from .outcomes import summary as outcome_summary
+
+    outcomes = outcome_summary(top, since_day)
     debt = dec.open_debt(top)
     referred = dec.referrals(top)
     from .policy import PolicyError, load_policy
@@ -185,6 +198,20 @@ def build(cwd: str, since: str = "7d") -> dict[str, Any]:
             "pre_answered": now["pre_answered"],
             "answers_matching_proposal": decided["matched_proposal"],
         },
+        # The experiment behind intent capture: does one line at task start make card questions unnecessary?
+        # "within" is a word overlap between the intent and the finding's subject, counted at card time; the
+        # accepted/declined split says how such findings were answered when they were. Nothing here is per person.
+        # Did the decisions hold? Read from the notes `gitvow outcomes` wrote; the digest never asks the forge.
+        "outcomes": outcomes,
+        "intent": {
+            "sessions_with_intent": sum(1 for s in sess_list if s.get("intent")),
+            "sessions": len(sess_list),
+            "cards_with_intent": now["cards_with_intent"],
+            "findings_on_those_cards": now["findings_with_intent"],
+            "within_intent": now["intent_covered"],
+            "within_intent_accepted": covered_answers["accepted"],
+            "within_intent_declined": covered_answers["declined"],
+        },
     }
 
 
@@ -281,6 +308,22 @@ def render(d: dict[str, Any]) -> str:
             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"
         )
+    from .outcomes import summary_line
+
+    oc_line = summary_line(d.get("outcomes") or {})
+    if oc_line:
+        out.append(oc_line)
+    it = d.get("intent") or {}
+    if it.get("sessions"):
+        line = f"Intent: {it['sessions_with_intent']} of {it['sessions']} session{'s' if it['sessions'] != 1 else ''} stated one"
+        if it.get("cards_with_intent"):
+            line += (
+                f" · {it['within_intent']} of {it['findings_on_those_cards']} card finding{'s' if it['findings_on_those_cards'] != 1 else ''} "
+                f"fell within it"
+            )
+            if it.get("within_intent_accepted") or it.get("within_intent_declined"):
+                line += f" ({it['within_intent_accepted']} accepted, {it['within_intent_declined']} declined)"
+        out.append(line)
     if ds.get("debt_items"):
         out += ["", "### Decision debt"]
         for o in ds["debt_items"]:
@@ -298,6 +341,8 @@ def render(d: dict[str, Any]) -> str:
         for s in d["sessions"]:
             sh = "n/a " if s["share"] is None else f"{s['share']:.2f}"
             plan = f'  "{s["plan"]}"' if s["plan"] else "  (no plan recorded)"
+            if s.get("intent"):
+                plan = f'  intent "{s["intent"]}"' + plan
             after = (
                 f"  · {s['human_after']} human edit{'s' if s['human_after'] != 1 else ''} after"
                 if s["human_after"]

{gitvow-0.29.2 → gitvow-0.31.0}/src/gitvow/hooks/__init__.py

@@ -9,6 +9,7 @@ import time
 from typing import Any
 
 from .. import decisions as dec
+from .. import intent as intent_mod
 from .. import snapshots
 from ..paths import is_credential_path
 from ..policy import PolicyError, confirm_message, evaluate, load_policy, message_for
@@ -19,7 +20,7 @@ from ..transcript import summarize
 
 NOTES_REF_PREFIX = "gitvow"  # refs/notes/gitvow/<session-id>; gitvow 0.1 wrote the single ref refs/notes/sessions
 LEGACY_NOTES_REF = "sessions"
-NOTE_SCHEMA = 7  # 7 (0.18): decisions[].answer may be "observed"; note gains edits_outside_repository. 6 added `to` to decisions[]: a referral may name who the question should have gone to
+NOTE_SCHEMA = 8  # 8 (0.30): note gains `intent`, decisions[] gain `intent_covered`. 7 (0.18): decisions[].answer may be "observed"; note gains edits_outside_repository. 6 added `to` to decisions[]: a referral may name who the question should have gone to
 # `git commit`, including the global options that may sit between the two words. `git -c k=v commit` and
 # `git -C dir commit` are the same act and used to slip past a `\bgit\s+commit\b` match entirely, which made
 # the card trivially avoidable by anyone who knew it. Options are enumerated rather than matched loosely so
@@ -59,9 +60,40 @@ def session_start(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
     )
     st.pop("pending_commit", None)
     st.pop("card_ack", None)
+    if not same_session:
+        st.pop("intent", None)  # an intent belongs to one session; the next task states its own
     save_state(cwd, st)
     log_event(cwd, "session_start", {"session_id": h.get("session_id")})
-    return 0, _rules_context(cwd, home)
+    ctx = _rules_context(cwd, home)
+    if toplevel(cwd):
+        ctx += intent_mod.context(cwd, _policy_or_empty(cwd, home), h.get("session_id"))
+    return 0, ctx
+
+
+def user_prompt_submit(h: dict[str, Any], home: str | None = None) -> tuple[int, str]:
+    """The first message of a session, when it states a task, becomes the session's intent in the person's words.
+
+    Only the first: a session has one intent unless a person restates it with `gitvow intent`. The prompt itself is
+    never stored; the first line, redacted and cut to MAX_TEXT characters, is. Off with policy `intent.from_prompt`.
+    """
+    cwd = h.get("cwd") or os.getcwd()
+    if not toplevel(cwd):
+        return 0, ""
+    pol = _policy_or_empty(cwd, home)
+    if not intent_mod.settings(pol)["from_prompt"]:
+        return 0, ""
+    sid = h.get("session_id") or load_state(cwd).get("session_id")
+    if intent_mod.current(cwd, sid):
+        return 0, ""
+    text = intent_mod.from_prompt(h.get("prompt"))
+    if not text:
+        return 0, ""
+    rules, _ = _rules_or_none(cwd, home)
+    if rules is None:
+        return 0, ""  # no redaction, nothing written: the person's words may hold a secret
+    who, _, _ = dec.identity(cwd)
+    intent_mod.record(cwd, text, who, "prompt", rules, sid)
+    return 0, ""
 
 
 def _rules_context(cwd: str, home: str | None) -> str:
@@ -188,6 +220,7 @@ def pre_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]:
     if _duplicate(h, cwd, "pre"):
         return 0, ""
     _note_touched(session_cwd, cwd)
+    intent_mod.propagate(session_cwd, cwd)
     try:
         pol = load_policy(cwd, home)
     except PolicyError as e:
@@ -259,10 +292,18 @@ def pre_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]:
                 st["pending_commit"] = time.time()
             save_state(cwd, st)
             proposed = dec.mark_proposals(cwd, pol)
+            covered = intent_mod.mark_coverage(cwd)
             log_event(
                 cwd,
                 "card",
-                {"findings": len(pending), "proposed": proposed, "mode": mode, "session_id": h.get("session_id")},
+                {
+                    "findings": len(pending),
+                    "proposed": proposed,
+                    "intent": intent_mod.current(cwd) is not None,
+                    "intent_covered": covered,
+                    "mode": mode,
+                    "session_id": h.get("session_id"),
+                },
             )
             return 2, dec.card(cwd, pol=pol, mode=mode)
         st["session_id"] = h.get("session_id") or st.get("session_id")
@@ -489,6 +530,7 @@ def post_tool_use(h: dict[str, Any], home: str | None = None) -> tuple[int, str]
         "subagents": summ["subagents"],
         "snapshot": st.get("last_snapshot"),
         "decisions": decisions,
+        "intent": st.get("intent"),
         "edits_outside_repository": st.get("edits_elsewhere") or {},
         "transcript": "kept local; see ledger",
         "redaction": "secrets/PII patterns, high-entropy tokens and custom rules replaced at write time",
@@ -528,6 +570,7 @@ def stop(h: dict[str, Any], home: str | None = None) -> tuple[int, str]:
         "tool_calls": summ["tool_calls"],
         "commits_during_session": commits,
         "repos_touched": st.get("repos_touched") or [],
+        "intent": st.get("intent"),
         "last_stated_plan": summ["last_assistant_text"],
         "usage": estimate(summ["usage"], _policy_or_empty(cwd, home)),
         "subagents": summ["subagents"],
@@ -540,6 +583,7 @@ def stop(h: dict[str, Any], home: str | None = None) -> tuple[int, str]:
 
 HANDLERS = {
     "SessionStart": session_start,
+    "UserPromptSubmit": user_prompt_submit,
     "PreToolUse": pre_tool_use,
     "PostToolUse": post_tool_use,
     "Stop": stop,

{gitvow-0.29.2 → gitvow-0.31.0}/src/gitvow/install.py

@@ -23,6 +23,20 @@ if [ -f "$STATE" ]; then
   SID=$(python3 -c "import json,time;s=json.load(open('$STATE'));p=s.get('pending_commit') or 0;w=s.get('pending_ttl') or 300;print(s.get('session_id') or '' if time.time()-p<w else '')" 2>/dev/null)
   STEP=$(python3 -c "import json;print(json.load(open('$STATE')).get('steps') or 0)" 2>/dev/null)
   if [ -n "$SID" ] && ! grep -q "^Gitvow-Session:" "$1"; then printf "\\nGitvow-Session: %s\\nGitvow-Step: %s\\n" "$SID" "$STEP" >> "$1"; fi
+  # The session's stated intent (gitvow intent, or the first message of the session) rides on every commit the
+  # agent makes, so a reviewer reads what the change was for next to what it did. Agent commits only: SID is set
+  # only inside the window after the gate saw the agent's git commit.
+  if [ -n "$SID" ] && ! grep -q "^Gitvow-Intent:" "$1"; then
+    python3 - "$STATE" "$1" <<'PY' 2>/dev/null
+import json, sys
+i = json.load(open(sys.argv[1])).get("intent") or {}
+t = " ".join(str(i.get("text") or "").split())
+if t:
+    line = "Gitvow-Intent: " + t + " by " + str(i.get("by") or "unknown") + (" source=prompt" if i.get("source") == "prompt" else "")
+    with open(sys.argv[2], "a") as fh:
+        fh.write(line + "\\n")
+PY
+  fi
   # Decisions recorded with `gitvow decide` become Gitvow-Accepted/Declined/Referred trailers; findings nobody
   # decided become Gitvow-Open, on agent and human commits alike. A referral is its own trailer because "the
   # question reached the wrong person" is not an answer and must never be read as one.
@@ -162,6 +176,7 @@ def _hook_entries(cmd_prefix: str) -> dict[str, list[dict[str, Any]]]:
 
     return {
         "SessionStart": [entry("SessionStart", None)],
+        "UserPromptSubmit": [entry("UserPromptSubmit", None)],
         "PreToolUse": [entry("PreToolUse", "Bash|Edit|Write|MultiEdit|NotebookEdit|mcp__.*")],
         "PostToolUse": [entry("PostToolUse", "Bash|Edit|Write|MultiEdit|NotebookEdit")],
         "Stop": [entry("Stop", None)],