# Commit Guards > Load to add, tune, or debug a commit guard lane, its git hooks, or COMMIT_GUARDS_* settings. - Skill: `vanillagreencom/commit-guards-2` (Agent Skill, multi-file: 86 files) - Install (CLI): `npx skillmds@latest add vanillagreencom/commit-guards-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/vanillagreencom/commit-guards-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: vanillagreencom (https://skillmd.com/u/vanillagreencom) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/vanillagreencom/commit-guards-2 --- ## Project Instructions Problems with a kendex-owned skill go through `kendex report`; check ownership in the file first. # Commit Guards ```bash .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 | Check | Verdict | |---|---| | **todo-ban** | Any work marker (TODO, FIXME, HACK, XXX in comment-marker shapes) in a tracked, non-excluded file fails. No baseline. | | **byte-ceiling** | A new tracked file over the configured ceiling fails; an existing oversized file may hold or shrink but may not grow; lockfiles are exempt. | | **suppression-ban** | Blanket lint suppressions fail; reasonless Rust dead or unused allows may only tighten against the baseline. | | **conflict-markers** | An unresolved merge-conflict marker in a tracked, non-excluded file fails. | | **changelog-entries** | Each `COMMIT_GUARDS_CHANGELOG_PATHS` fragment is one Markdown list item in a Keep a Changelog section and at most `COMMIT_GUARDS_CHANGELOG_CAP` characters. | | **prose** | A history reference in Markdown named by `COMMIT_GUARDS_PROSE_PATHS` fails; `COMMIT_GUARDS_CHECKS` controls whether the lane runs. | | **md-format** | A hard-wrapped paragraph or list item, a missing blank line around a heading, fence or list, or a trailing-double-space break in Markdown named by `COMMIT_GUARDS_MD_PATHS` fails; `md-reflow` is the remedy. | | **md-refs** | A dead relative link, section, content citation or decision reference in selected Markdown fails. `COMMIT_GUARDS_MD_REFS_PATHS` selects documents; `COMMIT_GUARDS_MD_REFS_SOURCE_PATHS` selects source comments and TOML strings for `§` citations. The supported forms are in [CHECKS.md § md-refs](CHECKS.md#md-refs). | | **py-names** | An undefined name or a syntax error in a Python file fails, judged by ruff or, where ruff is absent, pyflakes; neither installed while a Python file is selected is exit 2. See [CHECKS.md § py-names](CHECKS.md#py-names). | | **comments** | A history reference in the comment text of a source file named by `COMMIT_GUARDS_COMMENT_PATHS` fails: an issue id (`GH_ISSUE_PATTERN`), `#NNN`, or a date. Optional audit; see [CHECKS.md § comments](CHECKS.md#comments). | | **commit-msg** | The header must be `type(scope)!: subject` within `COMMIT_GUARDS_SUBJECT_MAX`; a commit touching `COMMIT_GUARDS_CHANGELOG_REQUIRED_PATHS` also owes a changelog entry or `[no-changelog]`. | Full check shapes and scopes: [CHECKS.md](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](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](README.md#git-hooks); install mechanics: [DEVELOPMENT.md § Git hook install contract](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. | Key | Default | Meaning | |---|---|---| | `COMMIT_GUARDS_CHECKS` | `todo-ban byte-ceiling suppression-ban conflict-markers changelog-entries prose md-format md-refs py-names` | Batch check list (`commit-msg` never batches). Under `--skip-unscoped` a caller that stages nothing withholds the checks it hands no scope whose configured scope reads only the staged diff. | | `COMMIT_GUARDS_TODO_EXCLUDES` | `tools/todo-ban-excludes` | todo-ban exclusion list. | | `COMMIT_GUARDS_BYTE_CEILING_KB` | `200` | Byte ceiling in KB. | | `COMMIT_GUARDS_BYTE_EXCLUDES` | `tools/byte-ceiling-excludes` | byte-ceiling exclusion list (declared asset trees). | | `COMMIT_GUARDS_BYTE_BASELINE` | `tools/byte-ceiling-baseline` | byte-ceiling `--all` baseline: the object size each legacy oversized file is held to. | | `COMMIT_GUARDS_SUPPRESSION_EXCLUDES` | `tools/suppression-ban-excludes` | suppression-ban exclusion list. | | `COMMIT_GUARDS_SUPPRESSION_BASELINE` | `tools/suppression-baseline.tsv` | Bare-allow ratchet baseline. | | `COMMIT_GUARDS_CONFLICT_EXCLUDES` | `tools/conflict-markers-excludes` | conflict-markers exclusion list. | | `COMMIT_GUARDS_CHANGELOG_CAP` | `200` | Characters per changelog entry. | | `COMMIT_GUARDS_CHANGELOG_PATHS` | `changelog.d/*/*.md` | Space-separated globs naming the changelog fragments, matched against the full repo-relative path (`*` crosses `/`). | | `COMMIT_GUARDS_CHANGELOG_RECORD` | `CHANGELOG.md` | The collation destination; empty disables collation. | | `COMMIT_GUARDS_CHANGELOG_REQUIRED_PATHS` | *(empty)* | Globs whose change obliges a changelog entry, judged by `commit-msg`; empty switches the rule off. | | `COMMIT_GUARDS_PROSE_PATHS` | `SKILL.md */SKILL.md AGENTS.md */AGENTS.md CLAUDE.md */CLAUDE.md workflows/*.md */workflows/*.md agents/*.md */agents/*.md docs/architecture/*.md` | Space-separated globs naming the markdown the prose lane scans, matched against the full repo-relative path (`*` crosses `/`). | | `COMMIT_GUARDS_MD_PATHS` | `*.md` | Globs naming the markdown md-format and md-reflow take under `--all`. | | `COMMIT_GUARDS_MD_REFS_PATHS` | `PATHS_DEFAULT` in `scripts/md-refs` | Globs naming the Markdown documents md-refs judges. | | `COMMIT_GUARDS_MD_REFS_SOURCE_PATHS` | the `COMMIT_GUARDS_COMMENT_PATHS` default | Globs naming the source files md-refs reads for `§` citations in comment text. | | `COMMIT_GUARDS_MD_EXCLUDES` | `tools/md-excludes` | Exclusion list both markdown lanes honour in every scope, and md-reflow under `--staged` and `--all`. | | `COMMIT_GUARDS_MD_SCOPE` | `touched` | With no scope flag, `touched` runs md-format on staged files and md-refs on all configured documents when anything is staged; `all` checks every matching file. Under `touched` the batch may hand these lanes a commit range instead (`--base REF`, `--against REF`); under `all` it hands them `--all`, since a range is narrower than the sweep that setting asks for. | | `DECISIONS_DIR`, `DECISION_ID_PREFIX`, `DECISION_ID_WIDTH` | `docs/decisions`, `D`, `3` | The decider skill's scheme, read by md-refs to judge decision IDs; IDs are not judged where the directory is not tracked. | | `COMMIT_GUARDS_COMMENT_PATHS` | the extensions in [CHECKS.md § comments](CHECKS.md#comments) | Space-separated globs naming the source files the comments lane scans, matched against the full repo-relative path (`*` crosses `/`); replaces the default. | | `COMMIT_GUARDS_COMMENT_EXCLUDES` | `tools/comments-excludes` | comments exclusion list (generated, vendored, and immutable first-party files). `GH_ISSUE_PATTERN` (the github skill's key) declares the tracker ID shape; empty leaves ID checks inactive. | | `COMMIT_GUARDS_COMMENT_REFERENCE_TYPES` | `issue-id issue-number date` | Reference classes the comments lane checks; name at least one type. | | `COMMIT_GUARDS_COMMIT_TYPES` | `build chore ci docs feat fix perf refactor revert style test` | Accepted commit types. | | `COMMIT_GUARDS_SUBJECT_MAX` | `72` | Characters allowed in a hand-written commit header. | | `COMMIT_GUARDS_PRE_COMMIT_LOCAL` | *(empty)* | Repo-root-relative executable the pre-commit shim runs last. | Settings follow [README.md § Settings](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.** `patternreason` 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.** `pathN`, `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](CHECKS.md#suppression-ban). Hook install and removal details: [DEVELOPMENT.md](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.