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

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/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/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/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 a dev->main promotion lands, do exactly one forward-port PR (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

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.