branch-flow-gate

branch-flow-gate -- Trusted Advisor (auto-invoked)

Wrong skill? Branch-name regex check alone -> git-branch-conventions. Pull before resuming work -> branch-sync-gate. Per-team flow specifics -> team's own documentation.

Announce at start: "I'm using branch-flow-gate to advise on branch hygiene. (Auto-invoked by intent. The preflight script never blocks; the sentinel it writes is consumed by pre-push Gate 3 on pushes to dev/staging/main.)"

Core Principle

This skill strongly recommends branching patterns that keep teams aligned but never mandates or precludes deviation when a developer has a valid reason. Every advisory exits 0 from the skill / preflight script. Every advisory includes an explicit escape hatch.

Honest disclosure -- this is advisory in-script, hard-blocking at push time. The preflight writes a .branch-flow-cleared sentinel which is consumed by pre-push Gate 3 on pushes to dev/staging/main. Without a valid sentinel for the pushed SHA, Gate 3 refuses the push. Hotfix/release/backport branches don't push to those canonical targets so are de-facto exempt; if your flow pushes hotfixes directly to main, use a hotfix/* branch name (auto-exempt) or set GIT_BASE_OVERRIDE=1.

Auto-Invocation

This skill fires on intent:

• Creating a branch (checkout -b, git checkout -B, "branch off ...")
• Opening a PR/MR ("open a PR", "merge request", "ready to merge")
• Shipping ("ship this", "deploy", "push to prod", "release", "promote ...")
• Cross-environment moves ("cherry-pick", "back-sync", "forward-port", "rebase onto ...")
• Hotfix / revert language

When the user mentions any of these in conversation, this skill activates before the action and advises.

What It Advises On

Check	When it fires	What it suggests
Base alignment	Branch is not on the required base's first-parent chain	Rebase onto the recommended base, OR acknowledge if the deviation is intentional
Retry suffix	Branch name ends in -vN	Recover the original branch via amend + force-with-lease
Back-sync / mirror naming	Name matches back-sync/*, sync/*, mirror/*, etc.	Use forward-port semantics (branch off destination, pull source forward)
Anti-leak patterns	Diff contains literal <word>-internal-*, *-secret-*, etc.	Use FAKE-LEAK-PATTERN-FOR-TEST placeholder
Non-ASCII in diff	Added lines contain non-ASCII	GitLab ASCII-only commit-msg hook may reject
Identical error loop	Two consecutive opaque errors after retry	STOP and diagnose before retrying again

ALL advisories print a soft message and exit 0. The script never blocks.

Escape Hatches (in order of permanence)

1. Per-branch acknowledgement (most common):

   touch .git/base-advisory-ack-<branch-slug>
   

   The advisory will not repeat for this branch.

2. One-shot override (when you know what you're doing this time):

   GIT_BASE_OVERRIDE=1 git push
   

   Document the reason in your PR description.

3. Exempt prefix (documented deviation lane):

   • hotfix/* (emergency production patch)
   • release/* (release branch)
   • backport/* (backporting to older release)
   • tagged-release/* (release-tag work)

   Branches with these prefixes skip the base advisory entirely.

Mandatory Preflight (BEFORE every branch creation or PR)

# Auto-mode (checks current branch against required base from config):
tools/branch-flow-preflight.sh

# Explicit pair-mode:
tools/branch-flow-preflight.sh <source-branch> <target-branch>

# Identical-error stop helper:
tools/branch-flow-preflight.sh --identical-check "$ERR1" "$ERR2"

Always exits 0. Writes .branch-flow-cleared sentinel that pre-push Gate 3 consumes on pushes to dev/staging/main. The sentinel must match the pushed commit's SHA; missing or stale (SHA-mismatched) sentinels == refused push.

Multi-Team Config

For repos with heterogeneous flows, commit .git-guidance.yml at the repo root:

default_base: origin/dev

Currently only default_base: is read. A richer per-team mapping (with teams: and per-team exempt_prefixes:) is planned but not yet implemented in tools/branch-flow-preflight.sh. Until then, legacy teams needing a different base must set it as the repo-wide default_base and use the hardcoded exempt prefixes (hotfix/, release/, backport/, tagged-release/).

Hook Installation (advisory; not required)

To get advisory output automatically:

Lefthook (lefthook.yml):

post-checkout:
  commands:
    branch-base-advisory:
      run: ./tools/branch-flow-preflight.sh
pre-push:
  commands:
    branch-base-advisory:
      run: ./tools/branch-flow-preflight.sh

Husky (package.json):

"husky": {
  "hooks": {
    "post-checkout": "./tools/branch-flow-preflight.sh",
    "pre-push": "./tools/branch-flow-preflight.sh"
  }
}

post-checkout fires once when the branch is created (before any work is invested). pre-push fires once per push (last local chance to notice). Neither of these advisory hooks blocks.

Note: This repo's tools/pre-push (installed via tools/install-hooks.sh) is the authoritative path. It runs Gate 3 which consumes .branch-flow-cleared and does block when the sentinel is missing/stale on pushes to dev/staging/main. The Lefthook/Husky integrations above are for contributors who want advisory output earlier in the workflow; they do not replace the in-tree hook. If tools/pre-push is not installed in this clone, Gate 3 does not fire and pushes to dev/staging/main rely entirely on PR review -- see reference.md F10. Server-side enforcement (CI runners, merge-queue automation, bot merges) requires a server-side hook or branch-protection rule -- the local sentinel does not propagate.

Anti-Patterns to Avoid (in the skill, not the user)

• exit 1 in a guidance hook -- if it can block, it's enforcement, not guidance.
• Repeating the advisory on every checkout -- once per branch, at creation. Repetition trains dismissal.
• No escape hatch -- a tool with no override breeds resentment.
• Not suppressing hotfix/* -- every advisory tool that fires on emergencies loses developer trust.
• Raw merge-base without first-parent filtering -- false negatives when dev/main share recent history.
• Blocking CI status check -- surface advisories as PR annotations or comments, never required checks.
• Cascade-chasing after a promotion -- after dev->staging->main lands, do exactly two forward-port PRs (main->staging, main->dev) and STOP. Each forward-port adds a merge commit the source is now "behind" on; chasing that gap with another forward-port creates the next gap and so on infinitely. Equal trees = aligned, even with topology drift. See reference.md F11.

When the Advisory Should Be Heeded vs. Ignored

Situation	Action
Just-branched feature off dev	Advisory should be quiet (or PASS)
Forgot to fetch + dev moved -> stale-but-correct base	Advisory says "rebase recommended"; you can ignore for now
Cut from staging because of an integration test	Heed the advisory and rebase OR acknowledge with touch .git/base-advisory-ack-<branch>
P0 hotfix at 3am off main	Use hotfix/ prefix; advisory exempts
Renaming -v2 retry to canonical name	Heed and git branch -m; recover via amend + force-with-lease

Companion Skills

• branch-sync-gate -- pull-gate (REQUIRED before this skill)
• git-branch-conventions -- branch-name regex check
• finishing-a-development-branch -- handoff ceremony
• progressive-code-review-gate -- cr-battery + sentinel

Failure Modes

See reference.md for the catalogue and concrete advisory examples.