Skip to main content

​
What the reviewer sees

Read it top down. A commit with a plan that names the files it changed and a high agent share is what it claims to be. A commit whose plan is empty, or whose changed files the plan never mentioned, or whose agent share is low, deserves the diff read with more care. A commit without a trailer was made by a person and is reviewed the ordinary way.

​
Setting it up

Add one workflow to the repository:
The action fetches refs/notes/gitvow/*, runs gitvow report over the pull request’s commits, posts the report as a single comment that it updates on every push, writes the same report to the job summary, and fails the check when a commit carries a session trailer but its note is missing, which means the author’s notes were never pushed. Inputs, all optional:

​
Intent, standing and the facts, on the pull request

Since 0.41 each decision line carries two more things. cites obs_… names the observations the finding rested on, when the gate raised it from a runtime fact or a drift the store holds, so the reviewer sees the fact the question came from. record before this: … is the card’s own sentence about what this repository’s record said about the finding before the commit: no earlier decision, accepted three times by two people, declined last month. It is this repository’s record, computed from the branch the check has; the store’s standing across repositories is not available to a check. The description block gains Gitvow-Intent lines, the task in the person’s words, and Gitvow-Cites lines pairing a finding with its refs, so a squash commit inherits both.

​
Decisions on the pull request

Each agent commit’s report lists the decisions it carries: what was accepted or declined, by whom, with what scope and reason, any Gitvow-Open finding nobody decided, and any Gitvow-Referred finding that reached the wrong person. Referrals are counted and worded separately from open findings, because a reviewer who reads “3 open” chases the team and a reviewer who reads “3 waiting on security” chases security. When a decision’s scope does not cover the branch the pull request targets and that branch is in decisions.production_branches, the report reopens it: “accepted for staging; this pull request targets main”. The check does not fail on it; the reviewer decides. Each decision line names the owner of its path as it was when the finding was raised, and marks in bold a path that had none. When gitvow outcomes has graded a commit, its report carries an Outcome line: how it landed (a pull request, or directly on a production branch), any revert, and per decision whether it held. See Did the decision hold?.

​
Squash merges

A squash merge writes one new commit whose message GitHub takes from the pull request title and description. The original commits’ trailers do not reach the target branch unless they are in that message. The action therefore writes a block into the pull request description on every push:
The block is updated on every push and can be edited around. A squash commit inherits the trailers from the description. The session notes do not follow a squash on their own: git carries notes through amend and rebase, not through a new commit it cannot map to the old ones. Since 0.29 the action carries them: when the pull request is merged, it runs gitvow carry <base>..<head> <merge commit>, which writes one note per session onto the merge commit (the newest note as the body, every replaced commit under carried_from with its decisions and files, the decisions merged) and pushes refs/notes/gitvow/*. For that to run, the workflow must fire on the closed event and have contents: write (see the workflow above); carry-notes: "false" turns it off. Readers (report, why, recall, the record server) find a carried note on a commit even when the squash message lost the Gitvow-Session trailer. Where the repository merges or rebases, both the block and the carry are redundant and harmless. To produce the block by hand: gitvow report --base origin/main --decisions-summary; to carry by hand after a squash: gitvow carry origin/main@{1}..<branch> origin/main && git push origin 'refs/notes/gitvow/*:refs/notes/gitvow/*'.

​
Getting notes to the remote

Notes live on refs/notes/gitvow/<session-id> and git does not push them with a branch. gitvow install adds a pre-push hook that pushes those refs to the same remote every time you push, so nothing changes in your workflow. To push them by hand:

​
Running the report locally

​
Said versus did

The comparison is deliberately simple and transparent: it checks whether each changed file’s name appears in the agent’s last stated plan before the commit. It cannot judge whether the change is correct; it tells the reviewer where the agent’s stated intent and its actual edits diverge, and where no intent was stated at all. Anything smarter belongs in a separate reviewer, fed by this report.