# Red Bear OS — Optional Git Hooks

This directory documents the git hooks that operators can install for
Red Bear OS. Per AGENTS.md "absolutely NEVER DELETE, NEVER IGNORE"
rule, hooks are always **opt-in** — operators explicitly choose to
install them. No hook is auto-installed.

## Available hooks (2026-07-12, Phase 4.5)

### pre-push-checks.sh (recommended for serious operators)

**File:** `local/scripts/pre-push-checks.sh`

**Purpose:** Run 4 critical pre-flight checks before every `git push`.
Closes the "silent drift" gap identified in AGENTS.md "Daily-upstream-
safe workflow".

**Checks:**
1. `sync-versions.sh --check` — Cat 0 + Cat 1 + Cat 2 versions
2. `verify-fork-versions.sh` — Cat 2 fork supremacy + content check
3. `verify-patch-content.py` — no orphan patches in `local/patches/`
4. `verify-collision-detection.py` — no config-vs-package conflicts

**Install:**
```bash
cp local/scripts/pre-push-checks.sh .git/hooks/pre-push
chmod +x .git/hooks/pre-push
```

**Bypass:**
- `REDBEAR_SKIP_PRE_PUSH=1 git push` (env var)
- `git push --no-verify` (standard git bypass)
- Run with `--soft` for warn-only mode

**Why not pre-commit?** Pre-push is preferred because:
- Pre-commit would block every local commit (even non-bump commits)
- Pre-push is the right safety boundary: "before I share work with origin"
- Operators committing 5x/hour to a feature branch don't need every commit
  to re-verify 4 checks; they need it on push

### Future hooks (Phase 4.5+ forward work)

- **pre-receive on the server** — gitea can run a server-side hook
  that re-verifies every push. Combined with the client-side pre-push,
  this is defense in depth. Implementation requires gitea admin
  permission; operator-only.
- **commit-msg hook** — auto-prefix commit messages with Phase ID
  (e.g., `phase 4.5: ...`) so future audits can group by phase.
  Optional, helps with audit doc generation.

## How hooks relate to AGENTS.md

AGENTS.md "Daily-upstream-safe workflow" says:
> "we can sources are provisioned via provision-release.sh and
>  archived in sources/redbear-<release>/ build successfully."

This means: **before any fork-upstream sync, validate the state**.
The pre-push hook is the operator-side implementation of that
check — it runs the same 4 checks that build-preflight.sh runs at
build time, but on the operator's local repository state.

## Why hooks are opt-in

Per AGENTS.md "absolutely NEVER DELETE, NEVER IGNORE" rule:
- Hooks can interfere with operator workflows (false positives block pushes)
- Some operators prefer manual run of pre-push-checks.sh
- Local hooks do not propagate (each clone must re-install)
- Some operators have multiple clones (different operator workstations)

The opt-in nature respects operator autonomy. The hook is provided
in `local/scripts/` so operators can opt in by copying it to
`.git/hooks/pre-push`.

## Audit

This directory was created in Phase 4.5 (Round 5). The current
hook inventory is:

| Hook | File | Function |
|------|------|----------|
| pre-push | `local/scripts/pre-push-checks.sh` | Runs 7 pre-flight checks before push |
| commit-msg | `local/scripts/commit-msg` | Auto-prepends `phase X.Y:` to commit messages |
| (server-side) | (gitea admin only) | Pre-receive — defense in depth; not yet implemented |

## Full Tool Inventory (Round 10)

The build system has grown organically across 9+ rounds. Here is
the complete tool inventory for reference.

| Tool | Type | Purpose | Modes |
|------|------|---------|-------|
| `patch-status.sh` | shell | Top-level consolidated report | `--brief`, `--json` |
| `sync-versions.sh` | shell | Cat 0+1+2 version sync + lockfile regen | `--check`, `--regen`, `--dry-run`, `--no-regen`, `--regen-only` |
| `verify-patch-content.sh` | shell↦py | Orphan patch detection | `--strict`, `--report action\|detail`, `--selftest` |
| `verify-fork-versions.sh` | shell | Cat 2 fork supremacy check | diverged mode; `REDBEAR_STRICT_DIVERGED_CHECK=1` |
| `verify-collision-detection.py` | python | Config [[files]] vs installs/files collision | `--strict`, `--selftest` (8 cases) |
| `pre-push-checks.sh` | shell | 7-check pre-push safety net | `--soft` for warn-only |
| `push-fork-branches.sh` | shell | Operator-reviewed fork push | `--execute` for actual push (default=print-only) |
| `unblock-base-push.sh` | shell | Base fork deadlock resolver | `path-a`, `path-b`, `path-c` for 3 operator paths |
| `commit-msg` | shell | Auto-phase-prefix hook | opt-in; install to `.git/hooks/commit-msg` |
| `build-preflight.sh` | shell | Build-time validation | Called by `build-redbear.sh` |

All scripts are under `local/scripts/` and are designed to be
operator-friendly. Hooks are strictly opt-in per AGENTS.md
"absolutely NEVER DELETE, NEVER IGNORE" rule.