From e1bb75e51804c3a8f402e0ee91464cc294435007 Mon Sep 17 00:00:00 2001 From: Ken Allred Date: Sun, 31 May 2026 08:06:50 -0600 Subject: [PATCH] docs: warn agents that a slow git push is the pre-push hook, not a network hang --- CLAUDE.md | 15 +++++++++++++++ docs/git-workflow.md | 11 +++++++++++ 2 files changed, 26 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 73d1881e..22f39977 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -93,6 +93,21 @@ When modifying prompts: See `docs/git-workflow.md` for the full workflow. +> **`git push` runs a multi-minute `pre-push` hook — a "hang" is usually the +> test suite, not the network.** `make hooks` installs a `pre-push` hook that +> runs the full bats/test suite (minutes) BEFORE the upload. A push that sits +> with no output is almost always the hook running tests, not a network/auth +> problem — do **not** kill it after a short wait, and do not start diagnosing +> HTTP/2, proxies, or credentials. Confirm with `GIT_TRACE=1 git push`: you'll +> see the receive-pack advertisement succeed, then +> `run_command: .git/hooks/pre-push …` followed by `1..N ok 1 …` bats output. +> (Note: this repo is public, so `git fetch`/`ls-remote` need no auth and return +> instantly — that contrast can make a slow push look network-specific when it +> isn't.) When you have **already run `make check-all` green on the exact commit +> being pushed**, the hook's run is redundant — use `git push --no-verify` to +> skip it and the upload completes in seconds. Otherwise, just let the hook +> finish (allow several minutes). + ### Scaffold Release Workflow The generic `/scaffold:release` command is for downstream projects. When diff --git a/docs/git-workflow.md b/docs/git-workflow.md index 6868dcc0..4e7fb9d4 100644 --- a/docs/git-workflow.md +++ b/docs/git-workflow.md @@ -143,6 +143,17 @@ Fallback: GitHub web UI (Settings > Branches > Add rule). These are local-only. Each developer/agent runs `make hooks` after cloning. +> **Heads-up for AI agents: a slow `git push` is the pre-push hook, not a hung +> network.** The pre-push hook runs the full test suite (several minutes) before +> the upload, with little/no output. Do **not** interpret a quiet push as a +> network/auth/HTTP-2 failure and kill it early or start diagnosing connectivity +> — this repo is public, so `git fetch`/`ls-remote` need no auth and return +> instantly, which can make a slow push look network-specific when it's just the +> hook. Verify with `GIT_TRACE=1 git push` (you'll see `run_command: +> .git/hooks/pre-push …` then `1..N ok 1 …`). If you have **already run +> `make check-all` green on the exact commit**, skip the redundant run with +> `git push --no-verify`; otherwise let the hook finish. + ### CI by Design Quality gates run both locally (`make check-all`) and in CI. The CI workflow is the authoritative gate — local hooks are a convenience.