Bridge Sync — Batch end-of-sprint upstream sync

/bridge-sync is the wide-net complement to /promote and /contribute.

Read the referenced file ONLY when triggered.

When to use

• End of a work-sprint, ready to publish all upstream-worthy changes at once
• After a refactor that touched many CORE+org files — manual cherry-pick is tedious
• When /promote has been deferred for days and there's a backlog
• When you want both bks-lab/open-bridge and your org overlay updated in one operation

NOT for:

• A single commit (/promote is leaner)
• File-level adaptation work (/contribute --adapt does that)
• USER-only changes (those stay local)

Arguments

Prerequisites

• Current branch must be user/*. Refuses on development / main.
• bridge-config.yaml.upstreams[] defines BOTH upstreams.
• git remote has origin (your fork) + upstream (typically <your-org>/<your-bridge>).
• For open-bridge sync: gh CLI authenticated with cross-fork PR rights.
• The org overlay must be a normal-layout repo. An overlay that carries overlay.manifest.yaml is a flat mirror read only below its defaults.source_root (tree/ when unset): /bridge-sync refuses it, because a cherry-pick lands every file at the overlay's repo root where no consumer reads it. Workflow Step 0a fetches each overlay and runs python3 scripts/overlay-export.py --check-ref {name}/{branch} (any non-zero exit refuses, an unfetched ref included). Build that overlay instead with python3 scripts/overlay-export.py --target <overlay checkout> --scope <tier> --dry-run, then the same command without --dry-run (docs/org-overlays.md § Authoring an overlay). open-bridge still syncs.

Decision Tree

User wants to...
├── Full sync (default)                  → references/workflow.md
├── Dry-run / preview routing            → references/workflow.md (stop after Step 4)
├── Sync only one repo                   → references/workflow.md § --repo override
├── Overlay with a manifest (flat mirror) → refuse; docs/org-overlays.md § Authoring an overlay
├── Configure scrub patterns             → rules/promote-safety.md per-repo blocklists
├── Tag the sync point                   → references/workflow.md § sync-tag
└── PR merge fails after squash-merge    → references/pr-recovery-patterns.md
    (stale-ancestor / non-fast-forward)

Safety

/bridge-sync runs a three-layer safety pipeline per destination (see rules/promote-safety.md for the full rule):

1. scrub_rules.<dest> — auto-rewrite during cherry-pick. Maps personal/internal tokens (your username, org, hostnames) to placeholders. Configured in bridge-config.yaml.promote.scrub_rules.
2. content_blocklist.<dest> — hard-block scan after scrub. Hits classify as scrubable (handled by layer 1), adaptable (defer for /contribute --adapt), or personal-PII (refuse).
3. Universal patterns — private keys, API tokens, paths — always blocked regardless of destination.

A commit hitting an adaptable pattern doesn't block the whole sync — it gets routed as 🟡 in the matrix and deferred. The clean commits still ship. --no-scrub only disables layer 1 (auto-rewrite); layers 2+3 always run.

Workflow recipes for conflict resolution (DU / UU / divergent structure), MIXED-CU cherry-picks, and residual-leak fixup (git commit --fixup + rebase --autosquash) live in references/workflow.md § Step 5.