kf-g-git-hooks-fix-verify-layering

Git hooks and post-edit hooks Fix / Verify division of roles

What can be gated by pre-commit / pre-push is Git hooks as the source of truth . Post-edit hooks (AI agent / editor project hooks) are for Fix immediately after editing + early detection .

Conclusion

Layer	Role	Whether to block commit / push
Immediately after editing	Post-edit hooks	Do not block (fail-open)
`git commit`	pre-commit	Block (verify gate)
`git push`	pre-push	Block (heavy check)

3-layer model

編集直後     編集後 hooks   Fix + 早期検知（非ブロック）
    ↓
git commit   pre-commit     Verify gate（ブロック）
    ↓
git push     pre-push       重い check（ブロック）

Reason for making pre-commit the source of truth

Also works for manual commit / editors outside AI agents / CLI
Can block commit / push The only common layer
Can ensure quality even without going through an agent

Position of post-edit hooks

Only immediately after AI agent file writes / Tab (inline completion) edits
Do not block commit → early fix loop for
If the tool in use can return additional_context equivalent, return lint / check results to the agent (post-edit event only)

The specific configuration of post-edit hooks depends on the tool in use. For Cursor, .cursor/hooks.json, for other tools, follow that tool's project hooks specification. The source of truth is Event concept（after agent edit / after tab edit if available）。

Division of roles for format / lint / check

Read according to the PJ's task name (mise run lint etc.).

Type	Fix (rewrite)	Verify（gate）
format	Post-edit hooks: formatter on the 1 edited file	pre-commit: format check (whole)
lint	Post-edit hooks: lint --fix → lint	pre-commit: lint (whole)
type check	Post-edit hooks: check according to target file type	pre-commit: check (always)
db / schema	Post-edit hooks: when editing schema / migration	pre-commit: same conditions as above
secrets / test	—	pre-commit / pre-push

Principle

Fix → post-edit hooks only
Verify（gate） → pre-commit / pre-push
Do not gate the same verify with post-edit hooks(early detection is OK)

Implementation guidelines

Command definition

Unify the source of truth for lint / format / check into the PJ's task (mise run etc.)
CI / pre-commit / post-edit hooks call the same task name. Do not duplicate definitions
Post-edit hooks process only the edited files . Do not do an initial whole-repository bulk fix

pre-commit / pre-push

When using the pre-commit framework, explicitly specify stages: [pre-commit] と stages: [pre-push] explicitly
Separate gitleaks etc. as pre-commit-only, and all tests etc. as pre-push-only
Consolidate hook installation into hooks-install -type tasks

Post-edit hooks

fail-open (do not stop the editing flow)
From hook input file_path and non-target extensions are no-op
Run only Fix commands (format / lint --fix). Delegate the verify gate to pre-commit
Set post-edit hooks only if the tool provides them (optional)

Anti-patterns

With post-edit hooks, format:check / make the full lint a gate
With pre-commit and post-edit hooks, separate command definitions have
Design that stops commits with only post-edit hooks when verify fails
Cramming heavy checks equivalent to pre-push into pre-commit

Related skills

New PJ initial setup: kf-g-project-bootstrap-new-project-rules（references/lint-fmt-hooks.md etc.)
Commit operation: kf-g-git-commit-staged-only-rules
Skill naming: kf-g-skill-naming-creation-organization-rules