cc-libs/docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md

ADR 0011: Git Hooks Own Commit/Push Verification

Status

Accepted

Date

2026-06-08

Context

The repository already has a CraftOS-PC harness (just test) and a fuller local CI path (just ci) that adds tool checks, luacheck, and harness regression guards. Agents and humans can also be asked to commit and push changes, which means verification can happen in two places: manually before Git operations and automatically inside Git hooks.

Running the same tests manually and then again in hooks makes commit/push workflows slower without improving the success contract. It also risks divergent habits between human and agent workflows if agents run one verification path and hooks run another.

Decision

Install two local Git hooks through just install / just install-git-hooks:

• .git/hooks/pre-commit runs just check test.
• .git/hooks/pre-push runs just ci.

When an agent is explicitly asked to commit and/or push, it should not run just test manually before the Git operation. The hook is the source of truth for that workflow: commit triggers just check test, and push triggers just ci.

Manual verification is still appropriate outside commit/push workflows. For example, run just test while developing a behavior change, and run just ci when checking the full local state without pushing.

Consequences

• Commit and push verification is consistent for humans and agents.
• Commit workflows avoid duplicating the same CraftOS-PC test run before and during git commit.
• Push workflows still get the full local CI gate before remote updates.
• The hooks are local files under .git/hooks, so developers should run just install after cloning or after hook behavior changes.

Future Work

• Revisit the split if just test becomes too slow for pre-commit or just ci gains checks that should also block commits.