Commit checkpoint - the gate before a commit or a publish
The protocol the git preferences' locked checkpoint entry points at: what runs before a non-trivial commit, the exemptions, the receipt the guard-ungated-commit hook reads, and the same ceremony for a push or a change-request merge by any route - git, a forge CLI, an API call or an MCP tool. The commit-message shape and the branch discipline live in the user's <docs-path>/preferences/GIT-PREFERENCES.md. Why each rule exists is references/evidence.md - an audit appendix, not a run-time load.
When to use
- Before any non-trivial git commit, a push or merging a change request (a PR or MR, by any tool) - 'commit this', 'push it', 'open the PR', 'merge it' - or before presenting a crypto / secret / auth / payment / data-access change, or when the commit guard denies one for a missing COMMIT-GATE or PUSH-GATE receipt.
- Not for the done gate before it, which proves the change works, or the commit message's shape, which the user's
GIT-PREFERENCES.mdowns.
Pre-commit checkpoint
On any non-trivial diff, before committing or presenting, in order:
Format. The formatter half is never skipped, and it must be FRESH: a formatter run from earlier in the session does not cover files edited since. After the last edit, run the project's own format CHECK - the command CI runs (a
format:checkscript, the CI workflow's format step), else the formatter's check mode - over EVERY staged path, inherited files included, not only the files this session edited; fix what it names with the formatter's write mode, re-stage, check again. Its clean verdict is the receipt'sformat:line.Review. Run the house review -
task-verify-codewhen a plan built the change, elsereview-codeover the paths this commit takes in (the Scope paragraph below), named as its target; both are model-invocable, so the gate holds in autonomous flows too - plus any diff gates named in the project's instruction file (AGENTS.mdorCLAUDE.md). A DISPATCHED domain-verifier pass over exactly this diff satisfies it the same way - the right call when the session's context is already heavy. Either way the review is a real invocation THIS session: a receipt claiming 'task-verify-code inline' or 'review-code inline' with no Skill call in the transcript is a replay from memory, not the gate. It must be FRESH, like the format check: a review that started before a file's last edit never saw it, so a fix made after the review getsreview-codeover the fixed files before the receipt.Security review when the diff touches auth, crypto, secrets, payment or data-access paths (
alfred-security.mdowns the trigger) - the security half below.Done gate. Satisfy the Definition-of-done gate.
Ask. No commit words from the user this conversation: name the paths (the scope derived fresh,
git diff HEAD --stat; git ls-files -o --exclude-standard, which never moves the index) and anything still owed (a gate not run, a review skipped), then put ONE AskUserQuestion - after steps 1-4, since an answer given before the review ran is void; a picked option is the receipt'sanswered:line. Words the user already typed for THIS commit skip it - they are theauthorized:line. The local commit takes the mark - it stays on this machine andgit reset --soft HEAD~1undoes it; when the question names anything still owed, 'Show the diff first' takes the mark instead, listed first:Commit <N files - the session's own paths> on <branch>? <VERIFIED phrase>. - 'Commit now (Recommended)' - stage exactly the named paths and commit them under the receipt - 'Show the diff first' - print the stat and the diff, then ask again; nothing is committed yet - 'Hold' - nothing is committed and no receipt is writtenThe
<VERIFIED phrase>says what ran on what: one build or test run of the whole tree verifies the tree, never each commit of a split - 'each commit builds' needs a run per commit.Receipt. Write the receipt below with
receipt.js, then commit, readgit log -1 --statback into the close, then clear it.
Scope - the session's own change. What was untracked before this change began is not part of
it: the docs hook lists it at session start, once per HEAD (<data root>/state/sessions/untracked-at-start-<HEAD sha>, named in the start block). Stage the session's own paths by name, review and count only those in
spec:, and name the pre-existing ones in one line as outside the change. One goes in only when the
user names it - the commit guard blocks a git add that would sweep it in (-A, ., a directory)
until <data root>/state/approvals/UNTRACKED-ALLOW lists it.
Exemptions. Skip the checkpoint for typos / one-line diffs, and a formatting-only diff inside the hook's trivial bar (below - above it a sweep needs a review like any change) - and for a diff an equivalent-or-stronger check just cleared: the active quality-loop's own dispatched re-verify plus final gate, or the cross-task flow's domain-verifier sign-offs plus the integration-reviewer final gate (a self-granted skip on any other reasoning is not this exemption; the security half has its own narrower carve-out, below). The formatter half runs even then. A quality-loop stage-boundary commit may exceed the one-logical-change size guidance when its stages share touched files - name the stages in the commit body rather than splitting an unverifiable diff.
The security half
alfred-security.md owns the trigger (crypto / secret / auth / payment / data-access work), the
honesty rules and the VERIFIED bar; review-security is how the review runs. Run it yourself,
first: load review-security with the Skill tool over the paths this commit takes in (the Scope paragraph above), named as its
target. It reads them without touching the index (a brand-new file included), applies its method and not-a-finding list, and
offers the security-auditor seat past its size bar. Inside a flow whose dispatch is explicit-only (the
solve flows) it runs inline unless the stop that led here offered the seat and the user picked it.
Never git add -N and never git reset in a review or scope read. The review's file list is the set
spec: counts - hold the two against each other before the verdict - and the security: line ends
- over <N> files, that count; the line is the review's verdict. Its leads are listed in the close and
never block VERIFIED.
The checkpoint exemption above skips this half only when the gate that cleared the diff carried a
security pass - the integration-reviewer gate does, the quality loop's does not - or when every path
in the diff is a test file: verify that from the diff's file list and name it in the close
(security review: skipped - test-only diff: <paths>).
The receipt
The checkpoint ends by writing its receipt: <data root>/state/approvals/COMMIT-GATE, five lines, then the format: and findings: lines -
VERIFIED <what was reviewed, one phrase>
authorized: "<the user's words asking for THIS commit, verbatim>"
head: <the sha the review ran against>
spec: <N files - the set it covered>
live-probe: <what was actually run, or NOT RUN - <reason>>
format: <the format CHECK command run> - clean over <N> staged files
findings: <the review's Findings field, copied - a count by severity, or none>
The quality-loop and cross-task gate exemptions count as VERIFIED - name the loop or gate. On the
user's explicit waiver the receipt is WAIVED - "<the user's words, verbatim>" alone - 'commit it' is
an instruction to commit, never a waiver of the review. spec: proves it covered every file the commit takes in:
the index, plus what -a, a chained git add or the paths it names add. The quoted words must carry a
commit verb left standing in its clause ('push it, don't commit' consents to no commit) and must not be
an option label this run wrote: consent given by picking an option is answered: <the chosen label>
instead. A review carried from an earlier cycle says so: carried: <cycle id>, reviewed <date>.
A project with no formatter at all writes format: none configured - clean over <N> staged files, nothing to check; a format line without the word clean is refused.
On a security-relevant diff the receipt adds an extra line: security: naming each category
checked and its verdict (security: auth ok, secrets ok, injection ok, data-access n/a). A
security claim with no security: line, or one that names no categories, is the one-line nod
alfred-security.md rejects - the guard reads it as no review at all.
Write it with this skill's bundled receipt.js, never by hand: it fills head:, spec: (the
count and the paths) and the counts on format: and security: from git, which is where hand-written
receipts were refused 37 times in three weeks. Resolve it from the skill's own folder (Node.js built-ins
only; run from the project):
R="${CLAUDE_SKILL_DIR}/scripts/receipt.js"
[ -f "$R" ] || R=.claude/skills/habits-commit-checkpoint/scripts/receipt.js
node "$R" commit --verified '<what was reviewed>' --authorized '<the user words, verbatim>' \
--probe '<what ran, or NOT RUN - reason>' --format '<the format check command, or none>' \
--findings '<count by severity, or none>' --paths <the session's own paths>
--answered '<label>' replaces --authorized for a picked option, --security '<each category and its verdict>' adds that line, --carried the carried line, and --all stands for git commit -a;
with nothing staged and no --paths it counts the whole tree minus what was untracked at session
start. push writes the PUSH-GATE receipt (--scope when the push spans projects), --waived '<the user words>' the waiver line alone, and clear commit removes the receipt. A receipt the guard would
refuse for a missing line is refused here first: exit 2, nothing written.
Write the receipt as its OWN tool call, before the call that runs git commit - one written inside
the same compound command is unauditable in the ledger. The shipped hook still ACCEPTS the atomic
write+commit shape (blocking it would reject the receipt discipline itself), so only this rule binds.
Own-call receipt, then the commit, then clear it.
The guard-ungated-commit hook blocks a non-trivial git commit without a fresh receipt. It
judges 'trivial' mechanically - at most 2 files and 15 changed lines across the session's change - this
commit plus the session's earlier commits that passed without a receipt - so a diff above that bar
needs a review whatever it changes, a formatting-only sweep included (spacing inside a string, or one
that splits a shell word, is code). Any VERIFIED line, whatever it says, needs a review of the code
that started in this session after the last edit to every file the commit takes in - a file whose bytes
a review saw (its staged copy too) still passes (a stash and pop), a review pointed at paths covers
those alone, a seat covers what its brief names (git diff HEAD for the whole change), a review call a
hook refused is no review, a verifier seat counts once it has reported (a background one at its
completed notification), and a review skill counts once its result line - Findings:, a loop's
Outcome: - follows it; never split a real change into small commits to slip under it. One receipt covers a reviewed batch: a later commit passes on it while its head: is an
ancestor of HEAD and every commit since touches only files its review covered; clear it after the LAST commit of the batch. The hook's staged-diff scan (a conflict marker, a
debugger, a focused test, a credential-shaped literal, a hidden character) is a fact check this receipt
never opens: remove the hit and stage again, or, on the user's 'Commit it as is' in the denial's own
ask, write the <data root>/state/approvals/STAGED-SCAN-ALLOW receipt it names.
A commit in a second tree the cross-project guard allows gets its own receipt in THAT tree's
<data root>/state/approvals/, written by receipt.js run from that tree and cleared the same way. A sibling repo is never committed, branched, pushed or sent as a change request
from here, and never OFFERED as an option in an ask of the run's own making - its change is a task
card under <docs-path>/work/cross-project-tasks/, printed as the docs-root rule's hand-off block.
Publishing - push and change-request merge
The same ceremony: a git push and a change-request merge - gh pr merge, glab mr merge, an MCP merge tool, any route - leave this machine,
and so does opening a change request from a CLI (gh pr create, glab mr create) where it would push the branch, so they carry their own
receipt, <data root>/state/approvals/PUSH-GATE, in the SAME five-line shape - VERIFIED <what is being published, one phrase>, authorized: "<the user's words asking for THIS publish, verbatim>",
head:, spec: <the commit set going out> and live-probe: - or WAIVED - "<their words>"; no
format: or findings: line, since each commit going out carried its own. Its spec: names what
LEAVES the machine, so it is required and never counted against the working tree. When the probe
actually ran something and the commit set touches more than one identifiable project, the receipt adds
an extra line - scope: <workspace, or the project list the probe ran>, never just the project that
was convenient to test; its edge cases, and when the gate does not apply, are references/publishing.md.
A no-fast-forward publish (git merge --no-ff, or a change-request merge) creates a NEW head. Run the merge
first, then write the receipt: head: names the resulting merge commit, never the pre-merge tip - a
receipt minted before the merge still reads the pre-merge tip, a different tree from what pushes.
Name what is going out and to which branch, then confirm it through ONE AskUserQuestion - a picked option is the receipt's
answered: <the chosen label>line. Words the user already typed for THIS publish skip the ask - they are theauthorized:line. A red the receipt'slive-probe:records on a check CI also runs is named in the question - 'CI runs , red here' - and 'Hold - fix the red first' replaces the plain Hold. Holding takes the mark, since a publish leaves the machine:Publish <the commit set> to <remote>/<branch>? It leaves this machine for CI and everyone on the branch. - 'Hold - push later (Recommended)' - nothing leaves the machine and no receipt is written - 'Publish' - push or merge exactly the set named aboveWrite the receipt as its own call.
Publish, read
git status -sbback into the close (the branch level with its upstream), then clear the receipt.Watch CI once - a pipeline watch, through whichever tool the session's
Forge:line names. Where the repo runs CI on the pushed ref, arm ONE watch on the pushed sha: a blocking watch as a background task when the tool has one - GitHubgh run list --commit <sha> --limit 1 --json databaseId,status, thengh run watch <id> --exit-status; GitLabglab ci status --live; an MCP pipeline-wait tool - else the status read every 60s in a background loop capped at 30 minutes, one line per poll. Never a foreground sleep loop. The close carries its verdict, orCI: pending - watching <run or pipeline id>when the turn ends first; a red verdict is reported when it lands, with the failing job's first error. No CI, or no tool that reads it: say so in one line.