# Red Bear OS — Build System Tools Reference

**Round 13** | **10 tools** | `local/scripts/`

This is the canonical reference for build-system operator tools.
Test scripts (~120) are excluded; see `local/scripts/test-*.sh`
for QEMU/runtime validation helpers.

## Quick Reference

| Tool | Purpose | Example |
|------|---------|---------|
| **patch-status.sh** | Consolidated status report | `./local/scripts/patch-status.sh` (--brief, --json) |
| **sync-versions.sh** | Cat 0+1+2 version sync + lockfile regen | `./local/scripts/sync-versions.sh --check` |
| **verify-patch-content.py** | Orphan patch detection + decision support | `python3 local/scripts/verify-patch-content.py --report action` |
| **verify-fork-versions.sh** | Cat 2 fork supremacy + content check | `./local/scripts/verify-fork-versions.sh` |
| **verify-collision-detection.py** | Config [[files]] vs recipe installs/files collision | `python3 local/scripts/verify-collision-detection.py --strict` |
| **pre-push-checks.sh** | 7-check pre-push safety net (opt-in hook) | `cp local/scripts/pre-push-checks.sh .git/hooks/pre-push` |
| **push-fork-branches.sh** | Operator-reviewed fork push helper | `./local/scripts/push-fork-branches.sh` (--execute) |
| **unblock-base-push.sh** | Base fork deadlock resolver (3 operator paths) | `./local/scripts/unblock-base-push.sh path-a` |
| **commit-msg** | Auto-phase-prefix hook (opt-in) | `cp local/scripts/commit-msg .git/hooks/commit-msg` |
| **build-preflight.sh** | Build-time validation (called by build-redbear.sh) | `./local/scripts/build-preflight.sh --config=redbear-mini` |

## Modes and Flags

### patch-status.sh
```
--brief    One-line summary: [orph=0/122 col=0 sync=OK fork=OK cargo=OK]
--json     Machine-readable JSON
(default) Full text report with fork push status
```

### sync-versions.sh
```
--check        Verify only, exit 1 on drift
--regen        Apply version sync + regen Cargo.lock files (opt-in)
--dry-run      Preview: show what --regen WOULD change, revert after
--no-regen     Apply version sync, skip Cargo.lock regen (same as default)
--regen-only   Only regenerate Cargo.lock files
(default)      Apply version sync only (lockfile regen is opt-in)
```

### verify-patch-content.py
```
--strict          Exit 1 on any orphan
--report action   Operator-decision suggestions (INTEGRATED/SUPERSEDED/etc.)
--report detail   Per-orphan listing with file paths
--selftest        5 regression test cases
(default)         Per-component summary
```

### verify-collision-detection.py
```
--strict    Exit 1 on any collision
--selftest  8 regression test cases
(default)   Per-config summary
```

### verify-fork-versions.sh
```
REDBEAR_SKIP_FORK_VERIFY=1            Skip entirely
REDBEAR_STRICT_DIVERGED_CHECK=1      Treat diverged as ERROR
(default)                               Diverged = WARN (advisory)
```

### pre-push-checks.sh
```
--soft    Warn-only, don't block push
(default) Block push on any check failure
```

### push-fork-branches.sh
```
--execute    Actually push (default = print-only with 5-second abort)
(default)    Show status + commands
```

## Where each tool runs

```
build-preflight.sh
  ├── sync-versions.sh --check
  ├── verify-fork-versions.sh
  ├── verify-patch-content.py
  └── verify-collision-detection.py

pre-push-checks.sh  (opt-in git hook)
  ├── sync-versions.sh --check
  ├── verify-fork-versions.sh
  ├── verify-patch-content.py
  ├── verify-patch-content.py --report action
  ├── verify-patch-content.py --selftest
  ├── verify-collision-detection.py
  └── verify-collision-detection.py --selftest
```

## See also

- `local/docs/HOOKS.md` — git hooks documentation
- `local/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md` — cumulative rounds 0-12
- `local/patches/README.md` — patch archive structure
---

**Last updated:** 2026-07-12 (Round 13)