katalyst-deploy-precommit-hook

name

katalyst-deploy-precommit-hook

description

Install a git pre-commit hook that runs `katalyst check` (and `katalyst fix --check`) so malformed frontmatter or non-canonical formatting fail the commit instead of landing. Use when a user wants katalyst enforced at commit time, a "pre-commit hook", or to block bad content before it reaches the branch. Paired with katalyst-deploy (chooses the mechanism) and katalyst-deploy-cli-gating (the alternative).

Deploy: pre-commit hook

Wire katalyst check into a git pre-commit hook so a commit that would introduce a violation fails before it lands. This is the simplest durable enforcement for git-backed content: it catches both human and agent commits, and needs no daemon or wrapper.

If you are not sure this is the right mechanism, start with katalyst-deploy, which compares this against CLI-gated writes.

Prerequisites

• katalyst on PATH (run ./bootstrap.sh if not).
• A git repository with a .katalyst/ config at its root.
• katalyst check passing today, so the hook starts from a clean baseline.

What the hook runs

Two commands, matching the CI gate (see the validation exit-code convention: 0 pass, 1 violations, 2 usage error):

• katalyst check — schema and structural checks over the project.
• katalyst fix --check — fails if any frontmatter is non-canonical, without writing.

Install

Most projects should use the repo's hook mechanism rather than a bare .git/hooks/ file, so the hook is versioned and shared. If the project uses the pre-commit framework, add a local hook; otherwise write .git/hooks/pre-commit directly. A ready-to-copy script is bundled at references/pre-commit.

Direct install:

cp references/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Then verify the gate fires by staging a change that violates a check and confirming the commit is rejected with the diagnostic.

Notes

• The hook is bypassable with git commit --no-verify; that is expected — it is a guardrail, not a lock. Pair it with the same checks in CI (see the project's CI configuration) so a bypassed commit still fails the build.
• Keep the hook fast: it runs check over the whole project by default. For very large corpora, scope it to staged files if commit latency becomes a problem.