gitvow 0.29.2__tar.gz → 0.30.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitvow
-Version: 0.29.2
+Version: 0.30.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) · [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.30.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) · [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.30.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitvow"
-version = "0.29.2"
+version = "0.30.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.30.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.30.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()
@@ -1065,6 +1102,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")

{gitvow-0.29.2 → gitvow-0.30.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.30.0}/src/gitvow/default_policy.json

@@ -198,6 +198,11 @@
     "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."
+  },
   "llm_classifier": {
     "enabled": false,
     "command": "",

{gitvow-0.29.2 → gitvow-0.30.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":
@@ -185,6 +195,18 @@ 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.
+        "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 +303,17 @@ 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"
         )
+    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 +331,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.30.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.30.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)],

gitvow-0.30.0/src/gitvow/intent.py

@@ -0,0 +1,222 @@
+"""Intent: what a task is for, in the person's words, stated once at task start and carried on every commit.
+
+The only record of what a change was meant to achieve used to be a commit message written after the fact, and
+every judgment downstream (the card, the reviewer, the outcome) was made without it. The intent is one line,
+kept in the session state (`.git/gitvow-session.json`, never in the tree), written by the prepare-commit-msg
+hook as `Gitvow-Intent: <text> by <who>` on each commit the agent makes in the session, and copied into the
+session note. It comes from one of two places:
+
+- `gitvow intent "<text>"`: a person states it (source `stated`).
+- the first message of a Claude Code session, when the policy allows it (source `prompt`, and the trailer says
+  so): the person's own words, first line only, redacted, at most MAX_TEXT characters. Slash commands and
+  one-word nudges are not an intent and are skipped.
+
+Coverage is the experiment this utility exists for: whether asking once at task start removes more consequential
+questions than gating each action does. A finding is *within* the stated intent when the words of its subject
+appear in the intent. That is a term overlap, nothing cleverer, and it never answers a finding: it is recorded on
+the finding, shown on the card, and counted by the digest so the ordering of the toolkit can be decided on data.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Any
+
+from .redact import redact
+from .state import load_state, log_event, save_state
+
+TRAILER = "Gitvow-Intent"
+MAX_TEXT = 200
+MIN_WORDS = 3
+INTENT_RE = re.compile(rf"^{TRAILER}:\s*(?P<text>.+?)\s+by\s+(?P<by>\S+)(?:\s+source=(?P<source>\S+))?\s*$", re.M)
+# Blocks a harness adds around or inside the person's message: pasted text, editor selections, system reminders.
+# None of them are the person's words about the task.
+_PASTED_RE = re.compile(r"<(pasted_content|system-reminder|ide_selection|ide_opened_file)[^>]*>.*?</\1[^>]*>", re.S)
+_TAG_RE = re.compile(r"<[^>\n]{1,80}>")
+_CAMEL_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+_SPLIT_RE = re.compile(r"[^A-Za-z0-9]+")
+# Words that name the shape of a finding rather than its subject. "edit", "route", "in" are in every finding;
+# matching them would make every intent cover everything.
+_STOP_WORDS = (
+    "a an and are as at be by for from i in into is it its of on or that the this to we with you your "
+    "add change edit edits fix make please update use want need should could would will can "
+    "file files path route command commit push pushing branch protected production cluster mutation "
+    "src lib app main index test tests yaml yml json py js ts go md txt"
+)
+STOP = frozenset(_STOP_WORDS.split())
+
+
+def settings(pol: dict[str, Any] | None) -> dict[str, Any]:
+    cfg = (pol or {}).get("intent") or {}
+    return {
+        "from_prompt": bool(cfg.get("from_prompt", True)),
+        "ask_when_missing": bool(cfg.get("ask_when_missing", True)),
+    }
+
+
+def from_prompt(prompt: str | None) -> str | None:
+    """The intent a first message states, or None when the message is not one (a slash command, a nudge)."""
+    if not prompt or not isinstance(prompt, str):
+        return None
+    text = _PASTED_RE.sub(" ", prompt)
+    text = _TAG_RE.sub(" ", text)
+    first = next((ln.strip() for ln in text.splitlines() if ln.strip()), "")
+    if not first or first.startswith("/") or first.startswith("!"):
+        return None
+    first = " ".join(first.split())
+    if len(first.split()) < MIN_WORDS:
+        return None
+    return first[:MAX_TEXT]
+
+
+def current(cwd: str, session_id: str | None = None) -> dict[str, Any] | None:
+    """The intent recorded for this repository's session, or None. With `session_id`, only if it is that session's."""
+    st = load_state(cwd)
+    i = st.get("intent")
+    if not i or not i.get("text"):
+        return None
+    if session_id and i.get("session_id") and i["session_id"] != session_id:
+        return None
+    return i
+
+
+def record(
+    cwd: str,
+    text: str,
+    by: str,
+    source: str,
+    rules: list[tuple[str, str]] | None = None,
+    session_id: str | None = None,
+) -> dict[str, Any]:
+    """Set the session's intent. Redacted, one line, at most MAX_TEXT characters. Replaces any earlier one."""
+    clean = " ".join((redact(text, rules) if rules is not None else text).split())[:MAX_TEXT]
+    if not clean:
+        raise ValueError("an intent needs some words")
+    st = load_state(cwd)
+    i = {
+        "text": clean,
+        "by": by,
+        "source": source,
+        "set_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        "session_id": session_id or st.get("session_id"),
+        "step": st.get("steps", 0),
+    }
+    st["intent"] = i
+    save_state(cwd, st)
+    log_event(cwd, "intent", {"source": source, "by": by, "session_id": i["session_id"], "chars": len(clean)})
+    return i
+
+
+def clear(cwd: str) -> bool:
+    st = load_state(cwd)
+    had = bool(st.pop("intent", None))
+    if had:
+        save_state(cwd, st)
+        log_event(cwd, "intent_cleared", {"session_id": st.get("session_id")})
+    return had
+
+
+def propagate(session_cwd: str, target_cwd: str) -> None:
+    """The session's intent follows the session into another repository it reaches (0.25 routing).
+
+    The intent lives in the state of the repository the session started in; a commit made through `git -C` in a
+    second repository reads that repository's state. Copy the intent across, once, when the target has none or has
+    one from a different session.
+    """
+    if session_cwd == target_cwd:
+        return
+    src = current(session_cwd)
+    if not src:
+        return
+    st = load_state(target_cwd)
+    have = st.get("intent") or {}
+    if have.get("text") and have.get("session_id") == src.get("session_id"):
+        return
+    st["intent"] = dict(src)
+    save_state(target_cwd, st)
+
+
+def trailer_line(i: dict[str, Any]) -> str:
+    line = f"{TRAILER}: {' '.join(str(i.get('text') or '').split())} by {i.get('by') or 'unknown'}"
+    if i.get("source") == "prompt":
+        line += " source=prompt"
+    return line
+
+
+def parse_trailer(body: str) -> dict[str, Any] | None:
+    m = INTENT_RE.search(body or "")
+    if not m:
+        return None
+    return {"text": m.group("text"), "by": m.group("by"), "source": m.group("source") or "stated"}
+
+
+def terms(text: str) -> set[str]:
+    """Words worth matching: split on punctuation and camelCase, lowercased, three letters or more, not STOP."""
+    out: set[str] = set()
+    for w in _SPLIT_RE.split(_CAMEL_RE.sub(" ", text or "")):
+        w = w.lower()
+        if len(w) >= 3 and w not in STOP and not w.isdigit():
+            out.add(w)
+    return out
+
+
+def covers(intent_text: str, finding: dict[str, Any]) -> bool:
+    """Whether the finding's subject shares a word with the intent. A term overlap, never an answer."""
+    want = terms(intent_text)
+    if not want:
+        return False
+    subject = " ".join(str(finding.get(k) or "") for k in ("subject", "path", "finding"))
+    return bool(want & terms(subject))
+
+
+def mark_coverage(cwd: str) -> int:
+    """Record on each open finding whether the stated intent covers it. Returns how many it covers."""
+    st = load_state(cwd)
+    i = st.get("intent") or {}
+    n = 0
+    changed = False
+    for f in st.get("findings") or []:
+        c = bool(i.get("text")) and covers(i["text"], f)
+        if f.get("intent_covered") != c:
+            f["intent_covered"] = c
+            changed = True
+        n += 1 if c and not f.get("decision") else 0
+    if changed:
+        save_state(cwd, st)
+    return n
+
+
+def card_header(i: dict[str, Any] | None) -> list[str]:
+    if not i or not i.get("text"):
+        return []
+    how = "from the first message of the session" if i.get("source") == "prompt" else f"stated by {i.get('by')}"
+    return [
+        f'Stated intent: "{i["text"]}" ({how}).',
+        "A finding marked within the intent shares its words; that is context for the answer, not the answer.",
+        "",
+    ]
+
+
+def context(cwd: str, pol: dict[str, Any] | None, session_id: str | None = None) -> str:
+    """One paragraph for the agent at session start: the intent if there is one, else how to get one."""
+    cfg = settings(pol)
+    i = current(cwd, session_id)
+    if i:
+        return (
+            f'\ngitvow intent for this session: "{i["text"]}" ({i.get("by")}, {i.get("source")}). '
+            "It rides on every commit as Gitvow-Intent. If the task changes, record the new intent with "
+            'gitvow intent "<the person\'s words>".\n'
+        )
+    if not cfg["ask_when_missing"]:
+        return ""
+    first = (
+        "gitvow records the first line of the person's first message as the intent of this session, in their words, "
+        "and it rides on every commit as Gitvow-Intent. "
+        if cfg["from_prompt"]
+        else ""
+    )
+    return (
+        f"\n{first}If that message does not say what the task is for, ask once, in one line, before the first edit, "
+        'and record their answer verbatim with: gitvow intent "<their words>". Never invent one.\n'
+    )