Commit Guards

Project Instructions

Problems with a kendex-owned skill go through kendex report; check ownership in the file first.

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.

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.

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. 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.

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. 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. 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 § Settings. 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 excludes the exact files the render writer lists in .kendex-generated.json. 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 unreadable or malformed inventory fails with exit 2; install or refresh kendex at the Git repository root in the main checkout and stage the inventory with the renders. Explicit ! rows still restore matching paths to the scan. Keep non-render exceptions in the reasoned exclusion list.