Problem
The generated gate runs fieldnotes verify --json over the whole repo and blocks if anything is stale, regardless of what is staged:
json="$(fieldnotes verify --json 2>/dev/null)" || exit 0
if printf '%s' "$json" | grep -qE '"stale":[[:space:]]*true'; then
...
echo " A staged change modified a file one of these notes pins."
exit 1
fi
The message asserts something the code never checked. If a note went stale three commits ago, the gate blocks a commit that touches nothing related and tells the author their staged change caused it.
The sharp edge
Arming the gate strands every sibling branch that predates the heal, because those branches still carry the pre-heal notes.
Concretely, on 2026-07-24 I healed 13 notes across two repos on fresh branches off main, then armed the gates. Both repos had other branches checked out with open PRs. Result:
$ cd bsoi-crm-app && .githooks/pre-commit; echo $?
1
$ cd blacksheepOI_website && .git/hooks/pre-commit; echo $?
1
Both branches were instantly unable to commit — through no fault of their own, and with a message pointing at the wrong cause. The escape is --no-verify (which is exactly the habit a gate exists to prevent) or landing the heal PR first.
The project already knows a weaker version of this rule — "never install the gate before healing." The real rule is broader: never arm the gate while any sibling branch still carries the pre-heal notes.
Two candidate fixes
- Scope the check to staged paths. Intersect
git diff --cached --name-only with the pinned paths of stale notes; block only on overlap. Makes the existing message true and stops stranding unrelated branches.
- Keep repo-wide blocking, fix the message. Defensible — "no commits while the repo's documented state is wrong" is a coherent stance. Then say so:
✗ commit blocked — N note(s) in this repo are stale (not necessarily related to your staged changes).
I'd take (1), with (2)'s honest wording as a fallback when the intersection is empty but staleness exists.
Docs
Whichever way it goes, install-git-hook's output should warn that arming the gate affects all branches and worktrees sharing the repo, not just the current one.
Problem
The generated gate runs
fieldnotes verify --jsonover the whole repo and blocks if anything is stale, regardless of what is staged:The message asserts something the code never checked. If a note went stale three commits ago, the gate blocks a commit that touches nothing related and tells the author their staged change caused it.
The sharp edge
Arming the gate strands every sibling branch that predates the heal, because those branches still carry the pre-heal notes.
Concretely, on 2026-07-24 I healed 13 notes across two repos on fresh branches off
main, then armed the gates. Both repos had other branches checked out with open PRs. Result:Both branches were instantly unable to commit — through no fault of their own, and with a message pointing at the wrong cause. The escape is
--no-verify(which is exactly the habit a gate exists to prevent) or landing the heal PR first.The project already knows a weaker version of this rule — "never install the gate before healing." The real rule is broader: never arm the gate while any sibling branch still carries the pre-heal notes.
Two candidate fixes
git diff --cached --name-onlywith the pinned paths of stale notes; block only on overlap. Makes the existing message true and stops stranding unrelated branches.✗ commit blocked — N note(s) in this repo are stale (not necessarily related to your staged changes).I'd take (1), with (2)'s honest wording as a fallback when the intersection is empty but staleness exists.
Docs
Whichever way it goes,
install-git-hook's output should warn that arming the gate affects all branches and worktrees sharing the repo, not just the current one.