refactor(git-branches): retrofit to the ADR-0020 context contract

Description 612 -> 273 chars, body 1124 -> 457 words. Branch patterns,
operations, merging, comparison, and the orchestrator contract move to
references/.

Corrects rebase routing in four places: this skill sent rebase to
git-history, which carries no rebase content and disclaims it. Rebase is
git-commits'; cherry-pick and revert stay git-history's. Drops a Step 3
gate on a rebase flow this skill does not have.

plugins/git/.apm/skills/git-branches/SKILL.md

@@ -2,13 +2,11 @@
 name: git-branches
 
 description: >
-  Use when managing the full lifecycle of git branches: create feature/hotfix/release branches
-  (gitflow, GitHub Flow, or custom patterns from config), switch, delete, rename, and track branches,
-  or retrieve branch intent metadata. Handles branch protection safety checks and returns structured
-  results for agent composition. Use even if the user doesn't explicitly mention branch names — they
-  may be asking about "fixing something" or "shipping a feature", which implicitly requires branch
-  management. Do not use when the user needs only commit operations (use git-commits) or history
-  inspection (use git-history).
+  Use when creating, switching, deleting, renaming, tracking, merging, or comparing
+  local git branches under GitHub Flow or Gitflow.
+  Not writing or rewriting commits -> `git-commits`.
+  Not history inspection -> `git-history`.
+  Not a Gitea remote's branches -> `gitea-branches`.
 
 metadata:
   category: git
@@ -21,92 +19,57 @@ metadata:
 
 ## Gotchas
 
-- **Branches are cheap; deletion is cheap but risky.** Deleting one requires checking if commits on it are reachable elsewhere; always confirm before deleting, as it may lose unmerged work.
-- **Uncommitted changes can block branch switches.** `git switch` aborts if local modifications conflict with the target branch. Offer to stash changes before switching when this happens, don't force a checkout.
-- **Tracking relationships matter for coordination.** Agents pushing on behalf of users should always set tracking (`-u origin <branch>`) so later pushes/pulls know the target. Without it, commands fail or target the wrong remote branch.
-- **Gitflow vs. GitHub Flow are not compatible.** Gitflow requires `develop` and `release/*` branches with `--no-ff` merges; GitHub Flow uses only `main` and feature branches with fast-forward. Read the repo's config or ask the orchestrator which pattern to use — don't guess.
-- **Naming collisions with tags.** A branch and tag can have the same name. Prefer `git switch` over `git checkout` for branch operations — verify which ref you're targeting with `git branch --list <name>` / `git tag --list <name>` if the name could be ambiguous, and disambiguate explicitly with `refs/heads/<name>` (branch) or `refs/tags/<name>` (tag) where a command accepts either.
-- **Never force-push `main` or `master`.** This is a hard refusal, not a confirmation gate — it applies even if the caller passes `confirm: true`. Deleting or renaming `main`/`master` in a way that would require a force-push to reconcile the remote (e.g. force-deleting and recreating it, or renaming it out from under in-flight work) must be rejected outright; explain why and suggest a non-destructive alternative (e.g. a new branch) instead of proceeding.
+- **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears.
+- **A branch and a tag can carry the same name.** Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/<name>` or `refs/tags/<name>`.
+- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead.
 
-## Branch Patterns
+## Step 1 — Determine the branching pattern
 
-Default to **GitHub Flow** (simpler, modern, CI/CD-friendly). Fall back to **Gitflow** only if the repo's config specifies it or the branch structure shows it in use (presence of `develop` or release branches).
+Read `branching_pattern` from the git plugin config (`.claude/plugins/git/config.json`; the plugin root's `config.example.json` shows the shape). Default: `github-flow`. With no config, infer Gitflow from the presence of a `develop` or `release/*` branch, and GitHub Flow otherwise.
 
-**GitHub Flow:**
-- Base: `main`
-- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
-- Merge: fast-forward when possible (preserves linear history)
-- Delete after merge
+The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`.
 
-**Gitflow:**
-- Base: `main` (production) + `develop` (integration)
-- Feature branches: `feature/<feature-name>` (from `develop`)
-- Release branches: `release/X.Y.Z` (from `develop`, merged to `main` + `develop`)
-- Hotfix branches: `hotfix/X.Y.Z` (from `main`, merged to `main` + `develop`)
-- Merge: always use `--no-ff` to preserve branch structure
+## Step 2 — Dispatch on the action
 
-## Workflow
+| Action | Reference |
+|---|---|
+| create, switch, delete, rename, track, list, get-intent | `references/branch-operations.md` |
+| merge a branch, resolve merge conflicts | `references/merging.md` |
+| compare two branches, find their divergence | `references/comparing-branches.md` |
 
-- [ ] **Determine pattern:** Check git plugin config (`.claude/plugins/git/config.json`, if present — see `config.example.json` in the plugin root for the expected shape) for `branching_pattern` (default: `github-flow`). If not set, inspect repo for `develop` branch or `release/*` branches; if present, assume Gitflow.
-- [ ] **Create branch:** Use `git switch -c <branch> <base>`. Base defaults to config's `base_branch` (usually `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`).
-- [ ] **Track remote:** If pushing, always use `git push -u origin <branch>` to establish tracking.
-- [ ] **Safety checks before destructive ops:** Before delete/force-push/rebase with history loss, check: (1) Is this branch tracking a remote? Warn if yes. (2) Are there unpushed commits? Warn if yes. (3) Does the orchestrator call include `confirm: true`? Fail if not. For humans, prompt interactively.
-- [ ] **Return structured results:** Always return branch operations as JSON or structured text: `{ "action": "create", "branch": "feature/x", "base": "main", "tracking": "origin/feature/x", "intent": "implement feature X" }`. Agents need to parse this for subsequent operations.
-- [ ] **Retrieve intent (`get-intent`):** Git has no native field for free-text branch metadata — this skill doesn't persist it. On `create`, the `intent` value is only ever returned in the structured result; the caller (orchestrator or agent) is responsible for storing it if it needs to be looked up later. On `get-intent`, either parse it back out of the branch name convention (`feature/<intent-slug>`) or return `{ "intent": null }` if the caller never persisted the original create-time value — don't fabricate an intent.
+Load only the file the action needs. A destructive action still passes Step 3 first.
 
-### Command mapping for each action
+## Step 3 — Gate destructive operations
 
-- **delete:** `git branch -d <branch>` refuses if the branch has unmerged commits — prefer this by default. `git branch -D <branch>` forces deletion and discards unmerged work; only use it after the safety checks above pass and `confirm: true` is set. For a remote branch: `git push origin --delete <branch>`.
-- **rename:** `git branch -m <old> <new>`.
-- **list:** `git branch` (local only), `git branch -a` (all local + remote-tracking), `git branch -r` (remote-tracking only), `git branch --merged`/`--no-merged` (filter by merge status into current branch).
-- **get-intent:** No git command — see Workflow step "Retrieve intent" for how this is resolved.
-- **track (existing branch):** `git branch --set-upstream-to=origin/<branch>` sets tracking without a push; `git branch -vv` shows tracking state for all local branches.
-- **switch (existing branch):** `git switch <branch>` — switches to an existing local branch (aborts on conflicting local changes, see Gotchas). `git switch -` switches back to the previously checked-out branch.
+Before any delete or force-delete that loses history:
 
-## Merging
+- [ ] Does the branch track a remote? Warn if so.
+- [ ] Are there unpushed commits on it? Warn if so.
+- [ ] Did the caller pass `confirm: true`? Fail if not — for a human caller, prompt interactively instead of failing.
 
-Scope: fast-forward/merge-commit mechanics and conflict resolution only. Rebase, cherry-pick, and revert belong to `git-history`.
+These gates are passable. The `main`/`master` refusal in Gotchas is not.
 
-- **Fast-forward:** `git merge <branch>` — advances the pointer with no merge commit if the target hasn't diverged.
-- **True merge:** `git merge --no-ff <branch>` — forces a merge commit even when fast-forward is possible; required by Gitflow on all supporting-branch merges.
-- **Squash merge:** `git merge --squash <branch>` stages the combined diff without committing; follow with a manual `git commit`.
-- **Octopus merge:** `git merge branch-a branch-b branch-c` merges more than two branches at once; fails outright on any conflict, so use sequential two-way merges if conflicts are expected.
+## Step 4 — Set tracking
 
-**Conflict resolution:** when Git can't auto-merge, it inserts conflict markers and stops. Run `git status` to find conflicted files, edit them to resolve the markers, then `git add <file>` and `git merge --continue`. `git merge --abort` reverts to the pre-merge state. `git mergetool` opens the configured merge tool; `git diff --diff-filter=U` shows only conflicted files.
+When pushing a branch for the first time, always `git push -u origin <branch>`. Without an upstream, later pushes and pulls either fail or silently target the wrong remote branch, and the caller has no way to tell which happened.
 
-## Comparing Branches
+## Step 5 — Return a structured result
 
-- `git log main..feature` — commits in `feature` not in `main`.
-- `git log feature..main` — commits in `main` not in `feature` (reverse direction).
-- `git log --left-right main...feature` — both diverging sets (symmetric diff).
-- `git diff main...feature` — diff from the common ancestor to `feature`'s tip.
-- `git merge-base main feature` — print the common ancestor commit.
+Return every operation in this shape rather than prose, including failures — a calling agent chains its next operation on the result and cannot parse a sentence.
 
-## Integration with Orchestrator
-
-When invoked by `git-orchestrate`, accept requests in the form:
-```json
-{
-  "action": "create|switch|delete|rename|track|list|get-intent",
-  "branch": "<branch-name>",
-  "base": "<base-branch (optional, defaults to config)>",
-  "intent": "<human-readable intent (optional)>",
-  "confirm": "<true for destructive ops, omit for read ops>"
-}
-```
-
-Return results as:
 ```json
 {
   "success": true,
-  "action": "create|switch|...",
+  "action": "create|switch|delete|rename|track|list|get-intent",
   "branch": "<name>",
   "message": "descriptive message",
   "intent": "<intent if tracked>",
-  "tracking": "origin/<branch (if set)>",
+  "tracking": "origin/<branch, if set>",
   "error": "<error message if success=false>",
   "suggestion": "<recovery suggestion if applicable>"
 }
 ```
 
-If error is due to uncommitted changes, include `{ "suggestion": "stash changes and retry" }` so the orchestrator can offer automatic recovery.
+When the failure is uncommitted local changes, set `"suggestion": "stash changes and retry"` so the caller can offer recovery rather than surfacing a dead end.
+
+When a calling agent supplies a structured request rather than prose, read `references/orchestrator-contract.md` for the request schema.