Commit Guards

.agents/skills/commit-guards/scripts/commit-guards                   # batch: every enabled check over the whole tree
.agents/skills/commit-guards/scripts/commit-guards all --staged      # the same batch at commit scope
.agents/skills/commit-guards/scripts/commit-guards all --base origin/main # the same batch over a branch's changes (CI)
.agents/skills/commit-guards/scripts/commit-guards todo-ban     # one check by name, flags pass through
.agents/skills/commit-guards/scripts/md-reflow PATH...          # rewrite markdown to the format md-format judges
.agents/skills/commit-guards/scripts/install-git-hooks          # arm the git pre-commit/commit-msg/pre-push shims
.agents/skills/commit-guards/scripts/install-git-hooks --check  # read-only: are the shims still armed?

The checks

Full check shapes and scopes: CHECKS.md.

Exit codes: 0 clean, 1 violations, 2 usage, configuration, or collection error. An unmerged entry in a scanned path is a collection error.

Git hooks

Run scripts/install-git-hooks [--repo PATH] to arm the shims.

A pulled render does not re-arm the helper; scripts/install-git-hooks --check names an outdated helper and the installer to run from the main checkout.

Pre-commit order: doc-limits --staged when installed -> preflight --staged when installed -> bot-instructions check --staged when installed -> commit-guards all --staged -> COMMIT_GUARDS_PRE_COMMIT_LOCAL when configured. commit-msg runs the message gate.

A repo-local entry names the paths it reads in COMMIT_GUARDS_PRE_COMMIT_LOCAL_PATHS. The chain runs it only when the commit touches one of those paths, a deletion or either side of a rename included, and otherwise prints pre-commit: local-entry=skipped and leaves the verdict to the other lanes. The chain reads the entry's exit as it reads every lane's: 0 clean, 1 violations, anything else a step that did not complete. It prints no install command of its own. An entry that needs a missing tool should print that tool's install command and exit 2; with the paths set, that refusal blocks only a commit that touches them.

pre-push runs doc-limits over the pushed tree and then the batch over what each pushed branch would do to the remote, so a state a replay carried in — a rebase, a cherry-pick, an autosquash, none of which run a commit hook — is judged before the branch leaves the machine by every lane but secrets. What a ref line deposits decides whether it is judged, so git push origin HEAD is judged like any other branch push; a deletion and a line landing on a tag or a note are skipped, and a line the lane cannot read is refused. Two refusals keep the verdict about the thing being pushed, since every range scope there ends at HEAD, every scan not handed a range reads the index, and every lane reads its tracked policy from the index: a branch whose tip is not HEAD, and an index holding content HEAD does not. Neither consults untracked files or unstaged edits.

The batch runs the enabled checks less the ones this scope leaves nothing for. A check this run hands no scope, whose configured scope then selects from the staged diff, opens no file at push — nothing is staged, which the refusal above makes certain — so it is withheld and named rather than counted clean. Where a range can be established the markdown lanes are handed it under their default touched scope, and judge what the branch changed, so a malformed document or a broken reference that a replay carried in is caught. Where none can be, the whole tree is the scope and those lanes are withheld: that sweep is absolute rather than ratcheted, so imposing it would refuse every push in a repository holding markdown that predates the guard, and choosing it is COMMIT_GUARDS_MD_SCOPE=all, the project's call. A project that has chosen it keeps it under every scope — a range is narrower than that sweep, so the batch hands such a lane --all rather than the range, and a document the range never touched still fails. Which lanes read that setting at all is taken off their own scripts rather than listed, and what it resolves to is asked of the setting's owner. secrets is withheld at every push, for the reason CHECKS.md § secrets gives.

What the scope rests on: the remote oid git puts on a ref line is read from the destination itself, and it is the only destination-bound evidence a pre-push hook gets. Where it is there, the batch is asked what landing HEAD at that oid would do to it (--against, two dots) rather than what the branch adds over the ancestor the two share — on a force-pushed branch those differ, and only the first is what the destination receives. changelog-entries asks instead which version increases the branch made: where the lane can establish the remote's default branch, its baseline excludes commits already there, else it is the remote head (DEVELOPMENT.md § The pre-push lane). Where the oid is absent — every branch's first push — the scope is a best-effort local one taken from this repository's refs for the remote, which record a past fetch. After a git remote set-url those refs still describe the previous repository, so an oversized file can read there as pre-existing. Where no boundary can be established at all — a push by direct URL, a push URL those refs do not describe, a branch nothing of which has reached the remote — the scope is the whole tree, where an oversized file is held to its row in the byte baseline: a repository carrying a file that was already oversized when it adopted the package, with no row for it, has such a push refused, and a baseline row, the excludes list or the bypass is the way past. Scope details: DEVELOPMENT.md § The pre-push lane.

Arming and disarming apply to the whole repository. Arm from the main checkout; an install from a linked worktree writes nothing and says whether the main checkout's arming is in place, exiting 0 when it is and 1 when it is not. A linked worktree is judged by its own render of the scripts when it carries one, and by the main checkout's copy when it does not. Disarm before removing the skill. Ownership and layering: README.md § Git hooks; install mechanics: DEVELOPMENT.md § Git hook install contract.

Configuration

Exclude immutable first-party sources, including applied SQL migrations, from the comments and prose lanes through their shared excludes lists. Keep preflight’s applied-migration-edited lane enabled as the authority on migration bytes. Set PREFLIGHT_MIGRATION_GLOBS for excluded migration paths outside that lane’s defaults.

Settings follow README.md § Setup. COMMIT_GUARDS_SETTINGS_FILE=/dev/null skips file sources; COMMIT_GUARDS_CHANGELOG_COLLATE=1 is environment-only, authorizes --collate on a clean index and working tree, and lets commit-msg count a record change as the release changelog entry.

Excludes format. pattern<TAB>reason per line (shell glob against the full repo-relative path; * crosses /); a pattern without a reason is a config error. A pattern opening with ! carves its matches back into the scanned set, and wins over every exclusion row whatever the order. To exclude a path that literally begins with !, escape it: \!foo. Baseline format. path<TAB>N, LC_ALL=C sorted, unique paths, N a positive integer: a count for suppression-ban, an object size in bytes for byte-ceiling. Initial suppression baseline: CHECKS.md § suppression-ban. Hook install and removal details: DEVELOPMENT.md.

Generated-file exclusions

Suppression-ban, conflict-markers, md-format and py-names exclude the exact files the render writer lists in .kendex-generated.json. A render's defect is its source's, judged in the author's repository, and a local edit to a render is overwritten. Adopted in-place skills and hooks remain governed because the writer leaves their source out of the inventory. Keep the inventory with the renders; adoption needs no manual ownership carve.

The inventory uses the exclusion list’s index-first read contract. An absent inventory is an empty one: nothing is excluded and every tracked file stays scanned, which is what a project whose items are all in-place, or one installed below the Git root, carries. An inventory the lane cannot read or load is the refresh owner's to repair, not the committer's. The lane names the cause, then prints inventory-unread=read:<status> or inventory-unread=load:<status>, excludes nothing and judges every file; when it finds anything it prints owner-unknown=<count> and exits 0, since a finding may sit in a render. Under a non-empty CI or GITHUB_ACTIONS the findings still block, so CI admits nothing an unread inventory left unclassified. changelog-entries --classify, which answers what a path is rather than gating, still refuses with exit 2. A malformed inventory's cause is inventory-status=<status>: 20 or 21 from the filter, jq's own status, or 127 when no jq is on PATH. The lines under it name the status word (documents, entry-shape, jq-error, or jq-missing), the jq that read the file, and the cause. For entry-shape the cause is the document's type when it is not an array, or else the index and the first 120 characters of the first rejected entry. The fix line names the remedy. For a malformed inventory, run kendex refresh at the Git repository root in the main checkout and stage the inventory with the renders. For jq-missing, install jq. For jq-error, the fix line names both remedies, the refresh and jq 1.7 or newer, because jq's status does not say which one applies. jq 1.6 finds a NUL in every string and changes the filter's 20 and 21 statuses under -e, so it refuses every inventory as jq-error. Explicit ! rows still restore matching paths to the scan. Keep non-render exceptions in the reasoned exclusion list.