docs: document git hook verification split

CLAUDE.md

@@ -15,6 +15,7 @@ Use `docs/README.md` as the entrypoint for CC:Tweaked, CraftOS-PC, Advanced Peri
 - When changing behavior, add as many useful CraftOS-PC tests as practical. It is acceptable to skip tests that require human-only validation, such as complex turtle motion, in-game UX feel, or visual approval, but still add unit-style non-regression tests for deterministic parts when possible.
 - Use `/apis/libtest.lua` for test scripts under `tests/`; `/programs/runtest.lua` prints `__TRAPOS_TEST_OK__` only after the suite passes.
 - `libtest` cancels each case after `3`s (`--timeout <s>` / `--no-timeout` to override); never commit a hanging test to `tests/`. Slow harness fixtures go in `tests/harness/` behind dedicated recipes. See `docs/adrs/adr-0009-layered-test-timeouts.md`.
+- Git hooks own commit/push verification: pre-commit runs `just test`, and pre-push runs `just ci`. When explicitly asked to commit and/or push, do not run `just test` manually first; rely on the hooks. See `docs/adrs/adr-0011-git-hooks-own-commit-push-verification.md`.
 - After editing Lua, run `just check` and fix all `luacheck` warnings.
 - Use 2-space indent, semicolons, and `local function`.
 - `require` paths are absolute ComputerCraft paths, for example `require('/apis/net')()`.

DEVELOPMENT.md

@@ -12,9 +12,11 @@ After cloning the repository, run:
 just install
 ```
 
-This creates `.env` from `.env.sample` when needed and installs the local Git hooks, including a pre-commit hook that runs `just ci`.
+This creates `.env` from `.env.sample` when needed and installs the local Git hooks: pre-commit runs `just test`, and pre-push runs `just ci`.
 
-`just ci` is the local verification entry point. Today it verifies that `craftos --version` reports v2.8.3 or newer, runs `just check` for `luacheck`, and runs `just test` for CraftOS-PC headless tests. Use `just craftos` to launch CraftOS-PC with repo-local save data under `.craftos` and read-only mounts for `/trapos`, `/apis`, `/programs`, `/servers`, and `/startup`. `just repl` opens the same environment with `--cli` for human interactive use only; LLM agents must not run it. Use the CraftOS-PC glossary when adjusting `--headless`, `--exec`, `--script`, `--rom`, or `--mount-*` usage.
+`just ci` is the full local verification entry point. Today it verifies that `craftos --version` reports v2.8.3 or newer, runs `just check` for `luacheck`, runs `just test` for CraftOS-PC headless tests, and runs the harness timeout regression guard. Use `just craftos` to launch CraftOS-PC with repo-local save data under `.craftos` and read-only mounts for `/trapos`, `/apis`, `/programs`, `/servers`, and `/startup`. `just repl` opens the same environment with `--cli` for human interactive use only; LLM agents must not run it. Use the CraftOS-PC glossary when adjusting `--headless`, `--exec`, `--script`, `--rom`, or `--mount-*` usage.
+
+When asking an agent to commit and/or push, rely on these hooks instead of duplicating `just test` manually before Git operations: pre-commit owns `just test`, and pre-push owns `just ci`. Manual `just test` and `just ci` remain appropriate when validating changes outside a commit/push workflow.
 
 Tests live under `tests/` and run inside CraftOS-PC through `just test`, which launches `/programs/runtest.lua`. API-level tests should use `require('/apis/libtest')({ ... })`, register cases with `testlib.test(name, fn)`, and call `testlib.run()` at the end. `libtest` tests remain normal ComputerCraft programs; the runner handles suite discovery, grouped output, and the `__TRAPOS_TEST_OK__` shell success contract. Pass `--pretty` to `just test` for grouped colored `[OK]`/`[KO]` statuses, or `--verbose` for additional runner/debug detail.
 

Justfile

@@ -1,5 +1,5 @@
 # Justfile for cc-libs
-# Run `just ci` to verify local tooling and lint Lua code.
+# Run `just ci` for full local verification.
 
 # List available recipes.
 default:
@@ -18,9 +18,12 @@ init-env:
 # Install Git hooks for this repository.
 install-git-hooks:
     @mkdir -p .git/hooks
-    @printf '%s\n' '#!/bin/sh' '' 'just ci' > .git/hooks/pre-commit
+    @printf '%s\n' '#!/bin/sh' '' 'just test' > .git/hooks/pre-commit
     @chmod +x .git/hooks/pre-commit
     @printf '%s\n' 'Installed .git/hooks/pre-commit'
+    @printf '%s\n' '#!/bin/sh' '' 'just ci' > .git/hooks/pre-push
+    @chmod +x .git/hooks/pre-push
+    @printf '%s\n' 'Installed .git/hooks/pre-push'
 
 # Verify the CraftOS-PC harness is installed and recent enough.
 check-craftos:

docs/adrs/README.md

@@ -18,3 +18,4 @@ Future ADRs can reuse the shape of the existing files when it is useful.
 - [`adr-0008-keep-tests-runnable-in-craftos-and-in-game.md`](adr-0008-keep-tests-runnable-in-craftos-and-in-game.md) - Keep tests runnable in CraftOS and in-game.
 - [`adr-0009-layered-test-timeouts.md`](adr-0009-layered-test-timeouts.md) - Layered test timeouts (libtest per-case + shell watchdog).
 - [`adr-0010-ccpm-package-manager.md`](adr-0010-ccpm-package-manager.md) - ccpm package manager (packages, registries, package-aware bootstrap).
+- [`adr-0011-git-hooks-own-commit-push-verification.md`](adr-0011-git-hooks-own-commit-push-verification.md) - Git hooks own commit/push verification.

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

@@ -0,0 +1,49 @@
+# 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.