Finishing a Development Branch

Confirm the final change has completed the project's independent quality-check and required checks. Evidence must describe the current tree: rerun affected verification after material edits or integration changes, and report unresolved failures. Do not add another whole-branch review or repeat an unchanged successful test suite merely to follow this skill.

Determine the repository, branch, base, worktree ownership, and uncommitted changes with read-only Git commands. Verify the intended target from the plan, upstream, or conversation before integrating.

Follow the integration action already authorized by the user. The design approval already covers commits, feature-branch pushes, creating the PR and the merge. First, if the project's rules require the user's approval for the merge, or the merge automatically releases, publishes or deploys to production - an environment that customers or users rely on (exception X2; an automatic deploy to an environment for checking behavior (such as staging) that does not touch production - the production database, live payments, or sending to real customers and the like - is not X2; judge by the effect on customers or users, not by the name) - finish the reviewable result and put that question in the final message. Only an answer to that item, or an instruction that names the operation and its target (range), counts as an X2 OK - not the design approval, a generic "continue", or an instruction that names no range. Otherwise look at the deviations from the design - both the spec / plan record and the PR body's deviation section. If there are none, merge with the project's merge procedure once quality-check is complete. If there are any, they change what was approved: finish everything else but create the quality-check flag only after the user's confirmation, ask in the final message as a separate decision ("merge with these deviations?"), and merge after the user's confirmation. A deviation that appears after that confirmation needs a new confirmation. Do not present an approval menu again. End with the final message of documents/development/development-policy.md §1.0 "承認後の進め方".

For a project that promotes main to a production branch (release or similar), the X2 question covers everything that goes out (§1.0 "承認後の進め方" 8). Before asking, run git fetch origin and fix the end SHA of the source. List the PRs not yet promoted up to that SHA: with merge-commit promotion, git log --first-parent --oneline origin/<release>..<SHA>; with squash promotion, main's commits never become ancestors of the production branch, so start from the previous source (the SHA recorded in the last promotion PR, or the first-parent main commit whose tree equals origin/<release>^{tree}); if no starting point is found, do not guess a list - write that it was not found in the final message. Show the list and the short SHA in the final message. As for any X2 OK, only an answer to the item that shows the list and the SHA, or an instruction that names the operation and the range, counts (on a "promote it" that names no range, build the list and the SHA and ask). Promote exactly that SHA; anything that lands before or after the OK stays out. When the promotion goes through a PR, do not use main as its head (push a temporary branch at the SHA and use it, for example git push origin <SHA>:refs/heads/promote/<short SHA>), or merge with gh pr merge --match-head-commit <SHA>. With squash promotion, write the source SHA in the promotion PR body (the next starting point). When this PR is not merged yet, add "this PR (after merge)" to the list; after the merge, if the first-parent range <the SHA you asked with>..<this PR's merge commit> holds only this PR, use that merge commit as the end, otherwise rebuild the list and ask again. After the OK, the AI merges and promotes; do not hand those operations back. The commands depend on the merge method: the project's own procedure holds the exact steps.

A project with no remote integrates into main without a PR. "No remote" means the remote you open pull requests on (usually origin) has no remote-tracking ref for the trunk (such as origin/main). A <remote>/main of a remote that takes no pull requests (a publishing, deploy or backup remote; a push-only remote gets one after its first push) does not count: with only such remotes, use this route, and do not push the feature branch to them. The hook's hints look at origin only; when the remote that takes pull requests has another name, go by this definition, not by the hint. Sending main on to a publishing, deploy or backup remote follows the project's rules. When it reaches production (exception X2), get the OK in the final message before the integration starts (before the detach in (4) / (5), or before git switch main in one checkout), then integrate and send in one go - never wait with the main checkout detached; after the OK, run integrate-check again before the detach (or git switch main), since the main checkout may have changed while you waited. Send after the integration (after (4)'s git push . HEAD:main; in (5) after the git merge --no-ff, before switching back; in one checkout after git merge) and before .quality-check-passed is deleted, from the checkout that holds the flag: git push <remote> HEAD:<trunk> from the feature worktree while it is on the feature, git push <remote> <trunk> while it is on the trunk. The main checkout has no flag, and once the flag is deleted the hook refuses the push. If the send is refused or fails (the deploy remote rejects it, a network or authentication error), keep .quality-check-passed and report git's output in the final message (exception X3); send again later from the checkout that holds the flag. Where main is not sent on every integration (origin is a bare backup sent now and then, for example), origin/main stays behind as the base ref and the next feature's context would include earlier changes: pass --base <trunk> to quality-context in both 4-0 and Step 6. With main open in another worktree: (1) finish quality-check in the feature worktree so the flag matches HEAD; (2) before touching the main checkout, run npx --no ai-dev-helm integrate-check --main <main checkout> in the feature worktree (npx -y @crearize/ai-dev-helm@<version in .ai-dev-helm.json> integrate-check --main <main checkout> where the CLI is not installed; --trunk <name> for a trunk other than main). It only reads - no push, merge or switch - and calls git with argument arrays, so no shell, quoting or encoding matters. It names what it finds: the main checkout not on the trunk, uncommitted changes to tracked files there, the trunk not being an ancestor of the feature, and anything the main checkout does not track at a path the feature adds, a rename's target included (an untracked or ignored file, a directory holding such files, a parent path that is a file; case follows the file system), and a file the feature changes that the main checkout marks skip-worktree or assume-unchanged (local edits git status does not show). Unrelated untracked files (the user's own material) are not looked at and do not block the integration; leave them alone. Read its last line. integrate-check: OK (exit 0): go on. integrate-check: NG (<trunk> is not an ancestor only): merge the trunk into the feature, re-run quality-check and start again from (1), integrate-check included (the main checkout is not touched, so this is no stop). integrate-check: NG - change nothing ... (exit 1): change nothing, stop integrating and report its output in the final message (exception X3; continue after the owner answers). Output that does not start with integrate-check: is no verdict (a usage error is exit 2; a missing CLI or an old devDependency's Unknown argument is no verdict either): fix the --main path or the like, or run npx -y @crearize/ai-dev-helm@<version in .ai-dev-helm.json> integrate-check ... instead. (3) Check that git push . HEAD:main is usable in this project (no deny rule in the agent settings such as Bash(git push:*), no project rule against it). (4) If it is, in the checkout that has main open, run git switch --detach; in the feature worktree, run git push . HEAD:main (git refuses anything but a fast-forward); in the main checkout, run git switch main. (5) If it is not, or a deny rule refuses the push after the detach, keep main detached and use the local merge of the branch-workflow skill, run where the flag is (the gate reads the flag of the checkout that runs the command, and the main checkout has none): in the main checkout, git switch --detach (unless it already is); in the feature worktree, git switch main, git merge --no-ff <feature>, git switch <feature>; in the main checkout, git switch main. (6) Delete .quality-check-passed. The detach, push, merge and switch stay plain git commands the quality gate sees; integrate-check never runs them.

If the final git switch main fails anyway (something was put into the main checkout after the check, for example), do not move or delete files and do not use git switch -f: leave the main checkout detached at the commit before the integration (the only case it stays detached) and report git's output (it names the files in the way) and the state in the final message (exception X3). If the push or the merge is refused for a reason other than a deny rule (the quality gate, git's non-fast-forward refusal and the like), put both checkouts back (git switch <feature> in the feature worktree if it is on main, git switch main in the main checkout) and re-run quality-check (after merging main into the feature if main has moved on); otherwise never leave the main checkout detached. Use this only when there is no remote that takes pull requests with a remote-tracking trunk. With the feature and main in one checkout, finish quality-check on the feature, switch to main and run git merge <feature>: the quality gate checks that the flag names that branch's tip and that main has nothing the branch lacks (sending main on to another remote: as above, before the flag is deleted). Delete .quality-check-passed after any merge into main.

Keep the project's branch protections and quality gate. A local merge or main push is not a substitute for a required PR. Investigate rejected pushes; do not force-push or bypass a gate without explicit applicable authorization.

When creating a PR, describe the problem, resulting behavior, and observed checks. Preserve the worktree for feedback. On an environment-owned worktree, use supported platform operations and leave cleanup to its owner.

Clean up only a worktree you created and only after its work is safely integrated or explicitly discarded. Check for uncommitted and ignored files before removal. Never force removal of files that exist nowhere else; resolve their disposition with the user. Do not infer permission to discard work from an integration request.