Skip to content

Write a policy

The policy is a JSON file of regular expressions. Start from the default:

gitvow install --user            # writes ~/.gitvow/policy.json if absent
$EDITOR ~/.gitvow/policy.json
gitvow check -- <a command>      # dry-run any rule

Shape

{
  "bash_deny":    [ {"pattern": "\\bgit\\s+push\\b.*(--force|-f\\b)", "reason": "force push"} ],
  "bash_confirm": [ {"pattern": "\\bgit\\s+push\\b",                  "reason": "pushing to a remote"} ],
  "path_confirm": [ {"pattern": "(^|/)values/production-[a-z]+/.*\\.ya?ml$", "reason": "edits production values"} ],
  "mcp_allow":    [],
  "mcp_deny":     [ "mcp__.*__(delete|remove|destroy|drop)_.*" ],
  "llm_classifier": { "enabled": false, "command": "" }
}

Patterns are Python re syntax, searched (not anchored) against the Bash command text or the file path; MCP patterns are matched against the whole tool name.

Rules proposed by a loop

A batch job outside gitvow can replay the policy over recorded sessions and propose rules for what the gate let through, each with evidence (events, repositories, engineers) and a price in questions per engineer per week. gitvow policy import <file> queues them; gitvow policy lists them, highest consequence first; gitvow policy accept <n> [--when observe] writes the rule into .gitvow/policy.json and commits that change alone, with Gitvow-Policy-Accepted and the evidence in the message; reject records Gitvow-Policy-Rejected on an empty commit so the loop does not propose it again. The policy stays code and every rule in it has a reviewed commit that says why it is there. Accepting into observe is the cheap first step: the rule records without asking, and the count it accumulates is the evidence for moving it to commit later.

Advice from running it

  • Put things you never want in bash_deny. Put things you want to hear about in bash_confirm. Confirm is cheap: it costs one question and the log shows how often it fires.
  • Name the files that decide who can do what in path_confirm: authorization filters, allow-lists, production deployment values, CI definitions. The default includes gitvow's own policy and the agent settings file, so an agent cannot quietly loosen the gate.
  • Leave mcp_allow empty until you know which MCP servers your team uses; a non-empty allow list turns every other MCP tool into a confirmation.
  • Watch the log for a week before tightening. Rules that never fire cost nothing; rules that fire on routine work will be resented and then removed.

The classifier

For decisions regular expressions cannot express, "is this sed -i on a config file part of the task or an attempt to edit the gate", set llm_classifier.enabled to true and command to a program (split like a shell would, but run without a shell, so redirections and pipes are not available and policy text can never become shell syntax) that reads {"tool_name":..., "tool_input":...} on stdin and prints ALLOW, CONFIRM <reason> or DENY <reason>. It runs only for calls the regular expressions did not decide. If it fails or times out, the call requires confirmation.

Validation

gitvow validates the file on every load: every entry needs a pattern, every pattern must compile. An invalid file fails closed, refusing all tool calls with the reason, so a typo is loud rather than silent.