From c594de07caf6801e755f289cc0fdd38a72ea3341 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 4 Jul 2026 20:44:58 +0200
Subject: [PATCH] docs(ci): document CI checks, local equivalents, and pre-push
 hook

---
 docs/ci.md | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/docs/ci.md b/docs/ci.md
index b3da8e13..73da7583 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -1,6 +1,46 @@
 # hive-ci: Forgejo Actions Runner
 
-The `hive-ci` module runs a Forgejo Actions runner in a `hive-ci` nixos-container, executing CI jobs from `.forgejo/workflows/ci.yml` (e.g., `nix flake check` on every PR).
+The `hive-ci` module runs a Forgejo Actions runner in a `hive-ci` nixos-container,
+executing CI jobs from `.forgejo/workflows/ci.yml` on every PR.
+
+## CI checks
+
+Three jobs run on every PR (and on `workflow_dispatch` for manual re-triggers):
+
+| Job | What it runs | Currently required |
+| --- | --- | --- |
+| **nix flake check** | treefmt + rustfmt formatting, `cargo clippy -D warnings`, `cargo test`, module evaluation | yes |
+| **tracker-tag lint** | flags `#NNN` issue tags in source and comments (`scripts/check-issue-refs.sh`) | no (red, non-blocking) |
+| **comment-block lint** | flags contiguous comment blocks over 30 lines (`scripts/check-comment-blocks.sh`) | no (red, non-blocking) |
+
+The tracker-tag and comment-block checks are non-blocking today (a hit fails the
+check but does not prevent merge) while the legacy backlog is cleaned up. They are
+expected to become required checks once the tree is clean.
+
+### Running checks locally
+
+Don't run `nix flake check` directly — it dispatches to the shared build farm and
+wastes a remote-builder slot. Use the devshell equivalents instead:
+
+```sh
+nix develop -c cargo clippy --all-targets -- -D warnings
+nix develop -c cargo test
+nix develop -c treefmt          # same as nix fmt; treefmt covers rustfmt + nixfmt + taplo
+sh scripts/check-issue-refs.sh  # tracker-tag lint
+sh scripts/check-comment-blocks.sh  # comment-block lint
+```
+
+A git pre-push hook that automates the two lint checks is provided at
+`scripts/pre-push`. Install it once per clone:
+
+```sh
+ln -sf ../../scripts/pre-push .git/hooks/pre-push
+```
+
+After that, any `git push` automatically runs both lints and aborts with a
+diagnostic if either fails — catching the issue locally before CI sees it.
+Note that the hook does **not** run `cargo clippy` or `cargo test` (those are
+slow); run those manually before pushing Rust changes.
 
 ## Operator bootstrap