#382 Add merge-pr skill family and rename merge config section

[williamthorsen]

What

Adds a /merge-pr skill that composes a merge-commit message and executes a GitHub PR merge through gh, removing the need to hand-type gh pr merge flags. The skill resolves scope and type from PR labels (or commit majority when labels aren't conclusive), composes the merge-commit body from the live PR description's ## What section, and runs an always-on approval gate before invoking the API. The new family mirrors the create-pr orchestrator-and-delegate pattern: merge-pr (user-invocable) owns all decisions; merge-gh-pr owns GitHub execution and pre-merge state validation; merge-bb-pr is a documented stub.

Also renames the merge_commit: preferences section to merge: and the corresponding describe-change.sh JSON output key from merge_commit_title to merge_title, reserving the merge: namespace for future action-of-merging settings (strategy, delete_branch) without churning preferences twice.

Why

Merging a PR by hand means typing gh pr merge flags and assembling the merge-commit message piecemeal. The result is inconsistent merge-log voice and missed opportunities to reuse the project's title-rendering machinery (describe-change.sh) and label-based scope/type inference (.meta/label-map.json). The skill captures the pattern once, runs it the same way every time, and produces merge artifacts the rest of the workflow can consume.

The merge_commit: rename is preparatory: with the section about to grow beyond title_format (eventually adding strategy, delete_branch, etc.), the original name is misleading — the rebase strategy produces no merge commit at all. Doing the rename now reserves the namespace cleanly and avoids a future double-churn of every project's preferences.yaml.

Details

Features

• New merge-pr orchestrator: --pr {n}, --scope, --type, --strategy, --delete-branch overrides; defaults strategy=squash, delete_branch=yes. Resolver functions (resolveStrategy, resolveDeleteBranch, scope/type pipeline) are written so adding preference-file lookup later is a one-line additive change.
• New merge-gh-pr delegate: single gh pr view --json call validates state, isDraft, mergeable, mergeStateStatus, reviewDecision, with a fail-closed policy for missing fields. Branch-sync check skips when the local branch isn't the PR's head ref or when the PR is from a fork (isCrossRepository). Strategy-flag mapping passes --subject only for squash and --body-file only for squash/merge. Saves a merge artifact recording PR URL, commit SHA, strategy, title, body, and branch-deletion outcome.
• New merge-bb-pr stub: prints resolved values and exits without invoking the Bitbucket API, parallel to how create-ticket handles Jira.
• Reserved-keys notice in merge-pr documents that merge.strategy and merge.delete_branch preference keys are reserved-but-unhonored in this iteration.

Fixes

• Pre-merge body composition: documents that the commit-majority parser strips a leading {ticket_ref} token before matching the conventional [scope|type: ] prefix, so projects whose commit.title_format includes the ticket reference are handled correctly.
• Pre-merge body composition: clarifies that the 30-character "thinness" threshold for ## What extraction is a default that an agent may override for short, intentional bodies (e.g., "Cosmetic only.").

Refactoring

• Renames merge_commit: to merge: in .agents/preferences.yaml, the agents README.md, _data/commit-format.md, describe-change.sh, and the shellspec test fixtures. JSON output key in describe-change.sh is renamed from merge_commit_title to merge_title. The user's ~/.agents/preferences.yaml is out-of-repo and requires a manual update to keep global merge-title rendering working.

Test plan

• On a draft PR: /merge-pr refuses with "PR is in draft state; mark it ready first."
• On a PR with merge conflicts: /merge-pr refuses with "PR has merge conflicts; resolve and retry."
• On a ready PR with the local branch checked out: /merge-pr shows the approval gate with rendered title, body, strategy, and delete-branch decision; refuses cleanly when declined.
• On a ready PR for a different branch (/merge-pr --pr {n}): no spurious "branch out of sync" refusal — the delegate detects the cross-branch case and skips the sync check.
• Override flags work: /merge-pr --strategy=merge and /merge-pr --delete-branch=no produce a merge with the expected non-default behavior.
• Update your global ~/.agents/preferences.yaml: rename merge_commit: → merge: and confirm merge-title rendering still works.

Closes #382

[github-actions]

Dependency audit

Production dependency audit passed.