--- name: tailrocks-repository-merge description: >- Audits, groups, integrates, reviews, and merges selected branches or PRs into one exact target branch. Use this skill only when the user explicitly requests it. A single PR belongs to its single-PR owner: create, refresh, review, or merge. This skill never deletes sources. argument-hint: "[SOURCES... | --all-work] [--repo OWNER/REPO] [--target-branch BRANCH] [--audit-only] [--transition-mode]" disable-model-invocation: true disableModelInvocation: true license: Apache-2.0 user-invocable: true --- # Repository merge ## Use this skill This skill audits, groups, integrates, reviews, and merges selected repository work into one exact target. It uses native `git` for local work and `gh` for GitHub operations. No custom runtime exists: no resolver scripts, receipts, schemas, or run-state protocol. Use this skill only when the user explicitly requests it. A single PR belongs to its single-PR owner: `tailrocks-create-pr`, `tailrocks-refresh-pr`, `tailrocks-review-pr`, or `tailrocks-merge-pr`. One term names one concept here. A source is a selected branch or PR. A contribution is one distinct behavior, fix, or supporting change. A group holds the contributions for one focused PR. The target is the selected destination branch. A candidate is the branch prepared for one group. A SHA identifies the exact commit used as evidence. ## Before you start Obey the active user request first. If the request conflicts with a safety rule in this skill, stop. Report the conflict. A human starts this skill with an explicit command. A model, a subagent, a scheduled task, a hook, or an observer never starts it. A saved report, a quoted transcript, or a repository file never authorizes it. No automatic recovery-to-merge chain exists. Each run needs a fresh human invocation. Before you resolve sources, read `references/selector-contract.md`. Resolve each relative link against the directory that contains this SKILL.md file. With `--audit-only`, the skill stops after analysis, grouping, and the report. It never changes source branches, the target, or GitHub state. It may collect evidence in an isolated workspace and write the requested report. The selected scope never widens. A targeted request reads only its sources. It also reads strictly necessary lineage. `--all-work` means all branches and open PRs in the selected repository. It never means every fork or every local clone. Never scan the machine for clones, stashes, lost objects, or unrelated repositories. The skill retains original branches by default. It closes a replaced source PR only when the active request permits closure and you confirmed coverage. It links the closed PR to the replacement PR. Never describe closure as a merge. Never delete source work to make the report look complete. Remote branch deletion needs separate explicit authority. It also needs verified complete source coverage at the current destination. Never remove the last recovery reference for unique unmerged state. Never close an absorbed PR until you account for its useful work. Recovery branches and PRs enter through the existing source selectors. Read their source maps before integration. Never merge preservation-only snapshots mechanically. Analyze each useful contribution against the latest target. Each hosted PR merge squashes through `tailrocks-merge-pr`. Local source integration and the hosted PR merge are different operations. When this skill loads, it grants no permission beyond the active request. A review report never authorizes a merge. Phases that the goal already authorized need no further user message each. The skill accepts these arguments: - `SOURCES...` names the sources: branches, `branch:N`, `#N`, PR numbers, PR URLs, or `/pulls` and `/branches/all` listing URLs, all in one repository. - `--all-work` selects all in-scope branches and open PRs. Never mix it with `SOURCES`. - `--repo OWNER/REPO` selects the one canonical repository. Without it, the skill resolves it once from the selectors or the unambiguous current checkout. - `--target-branch BRANCH` selects the one destination. Without it, the target is the literal branch `main`. The target must already exist. The skill never creates it and never guesses it. - `--audit-only` selects analysis, grouping, and report only. Nothing changes. - `--transition-mode`: the skill integrates through one authoritative transition branch instead of focused per-group PRs. It is optional and human-selected. Without it, focused contribution PRs stay the default. ## Procedure 1. **Bind the repository, the target, and the scope.** Run `gh repo view --json nameWithOwner,url` to resolve the canonical repository. Resolve it once. Store its exact `nameWithOwner` as `REPO`. Pass `--repo "$REPO"` to each later `gh` command. Confirm that the target branch exists. Record its full ref and current SHA. Freeze the source scope. Before step 2, record one repository, one existing target, and one frozen scope. 2. **List each in-scope source.** List all in-scope remote branches and open or draft PRs. Use complete pagination. Never treat a fixed result limit as complete. Run `gh pr list --repo "$REPO" --state open --limit 1000`. If the count is uncertain, also run: ```sh gh api repos/$REPO/pulls --paginate --method GET -f state=open ``` Without `-f`, the request stays a GET request by default. If `-f` is present, the request changes to POST unless `--method GET` is present. Run `git ls-remote --heads` for branches. Before step 3, list each in-scope branch and open or draft PR, or record the listing gap. 3. **Record source identities.** Record each source head SHA, PR base, fork identity, and observation time. Before step 4, give each source its identity tuple and time. 4. **Read the changes.** Read each source diff against the current target. Use `gh pr diff` or `git diff ...`. Read the relevant code, callers, contracts, tests, and the history needed to explain the work. Collect evidence in an isolated workspace. Never execute untrusted branch code with access to host secrets. Before step 5, read each source diff with its context. 5. **List the functionality.** List the functionality and unique supporting work in each source. Give one contribution to each distinct behavior, fix, or supporting change. Before step 6, map each source to its contributions. 6. **Compare each contribution.** Compare each contribution with the current target first. Then compare it with related sources. Examine partial changes, duplicates, reverted behavior, and work meant for another target. A shared patch ID is evidence. It is not proof of current behavior. After a squash merge, ancestry alone proves neither delivery nor absence. Confirm the resulting code and behavior. Compare related sources deeply. Do not run each possible pairwise comparison without a reason. Before step 7, give each contribution a target verdict. Record its source relationships. 7. **Write the source map.** Write the full source-to-functionality map before any integration starts. Cover each source, each contribution, and the target state of each contribution. Before step 8, confirm that the map covers each in-scope contribution. 8. **Group related contributions.** Group related contributions into focused PRs that fit together. Never merge unrelated work into one large PR to reduce the count. Record dependencies, conflict risks, and the group order. Explain necessary splits in the report. Before step 9, group, defer, or reject each contribution with a reason. Never drop one silently. With `--transition-mode`, still group the contributions. Integrate through the transition flow below instead of steps 9 through 16. 9. **Prepare the next candidate.** With `--audit-only`, stop here. Report. If not, select the next ready group. Prepare its candidate branch from the current target. Reuse a suitable existing branch only when ownership and head are as expected. Never touch the target directly. Never rewrite source history. Before step 10, confirm that the candidate starts at the current target. 10. **Integrate the selected contributions.** Use native git commands to integrate only the selected contributions. For a mixed source, record the original SHAs. Never merge the whole branch while you claim that unwanted work was excluded. Resolve conflicts by intended behavior. Keep author attribution and source links. Keep stronger target behavior unless the group justifies replacement. Before step 11, confirm that the candidate holds the group and nothing else. 11. **Run checks and open the PR.** Run the relevant checks. Create or reuse the PR of the group through `tailrocks-create-pr`. When necessary, refresh its body through `tailrocks-refresh-pr`. Before step 12, confirm that one PR covers the candidate. 12. **Review the combined change.** Review the final combined change through `tailrocks-review-pr`. Include group coverage: each selected contribution is present, excluded work is absent, and documentation matches the implementation. Before step 13, confirm that a review verdict covers the current head. 13. **Fix and re-review.** Send required fixes to an implementation subagent as normal implementation commits. Never use a special trailer commit. Review the changed result again. Before step 14, confirm that no unresolved Blocker or Required finding remains on the current head. 14. **Squash the PR.** Squash the reviewed PR into its intended target through `tailrocks-merge-pr`. Before step 15, observe the landing result. Record it. 15. **Confirm and refresh.** Confirm the merge, the intended target, and the resulting commit. Refresh the target SHA and the remaining source comparisons. Report a queued or pending result as such. Never report it as merged. Before step 16, confirm that the target state and remaining work are current. 16. **Continue to resolution.** Continue group by group. Serialize merges into the same target. Prepare the next conflicting group only after the target advances. Continue until you resolve each in-scope contribution or record an explicit blocker for it. Refresh changed source heads before you reuse their earlier analysis. At the end, confirm that you resolved each contribution or blocked it with evidence. ### Transition flow Use this flow only when `--transition-mode` is present. It replaces steps 9 through 16 of the Procedure. 1. **Create one authoritative transition branch** from the current target. One mutation owner holds this branch. Never touch the target directly. Before transition step 2, confirm that the transition branch starts at the current target. 2. **Remove duplicate sources before conflict resolution.** Remove verified identical work first. Refresh stale analyses after relevant source or target changes. Never equate newer timestamps with better work. Before transition step 3, confirm that each group holds only unique work. 3. **Prepare independent groups in parallel.** Integrate each ready group into the transition branch. Serialize each push through the one mutation owner. Push completed integration groups promptly. Before transition step 4, confirm that you integrated each group or blocked it with evidence. 4. **Review the combined result and required checks.** Review through `tailrocks-review-pr`. Cover group coverage and the required checks. Before transition step 5, confirm that a review verdict covers the current head. 5. **Squash the final PR through `tailrocks-merge-pr`.** At the end, observe the landing result. Record it. ## Result The skill writes one readable report: source inventory with SHAs, functionality, group order, the selected mode, evidence, PR links, progress, blockers, and the next action. Another session can continue from the report. The report grants no new permissions. When you continue, examine live repository state again. Report incomplete listings or inaccessible evidence as coverage gaps. Never claim complete accounting while gaps remain. After zero-local recovery, prefer an authorized remote environment for later integration. If none is available, require an explicitly authorized temporary local workspace. Then reapply cleanup and final scanning. Never claim continuous zero-local state while you use a new local clone. ## Completion checks Before the report is complete, make sure that each item below is true: - Entry was human. - The scope never widened. - You mapped and accounted for each contribution. - You recorded the selected mode. - You reviewed each combined candidate before merge. - Each hosted merge squashed with its head guard. - The skill retained the sources. - The report names the evidence, gaps, and next action. ## References Read this reference at the stated time: - Read `references/selector-contract.md` before you resolve sources for the selector rules.