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