Files

T

vasilito ffaa4c6bb4 phase 16.2: update docs for sync-versions.sh safe-by-default + --dry-run

- PATCH-PRESERVATION-AUDIT: add Phase 16.1 to cumulative reduction table
  (122→0 orphans, Round 17); update operator test section with all 6 modes;
  replace stale 'Round 3 final' re-run with current Round 17 verification
- TOOLS.md: add --regen and --dry-run flags; clarify default is opt-in
- HOOKS.md: add --regen and --dry-run to sync-versions.sh option list

2026-07-12 15:27:39 +03:00

4.7 KiB

Raw Blame History

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:

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

Install:

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

4.7 KiB Raw Blame History