worktree-done git:20261017.382f334A

Immutable. This exact content never changes and is served at /api/v1/blob/80dd50e22f6c40a1.

---
name: worktree-done
description: Use when the user says they are done reviewing or testing this worktree or task space and want its pull request merged. Verifies the worktree matches the PR, then enables auto-merge so GitHub merges it once required checks pass. Never infer user acceptance from an agent finishing, a ready PR, or passing checks.
---

# Worktree Done

The user's invocation accepts the version they reviewed and authorizes merging
this task's PR once the repository's required checks pass. It does not authorize
merging other PRs, deployment, or a release. Do not invoke it on the user's
behalf merely because implementation is finished.

Cleanup happens from outside this workspace with `worktree-cleanup`. Do not close
this workspace, remove its worktree, or delete its branch from inside it.

## Verify the accepted version

Work in this task's worktree (`git rev-parse --show-toplevel`). Find its PR with
`gh pr view --json number,state,isDraft,headRefOid,baseRefName,url,mergeStateStatus,statusCheckRollup,body`.
Stop and report, without merging, when:

- there is no PR, or it is closed or already merged;
- `git status --porcelain` shows uncommitted or untracked changes;
- after `git fetch`, local `HEAD` differs from the PR's `headRefOid`. New local
  commits, or remote commits the user has not reviewed, need their review first;
  do not commit or push new work as part of this acceptance;
- the PR's base is not the repository's default branch. Its base PR must merge
  first; GitHub then retargets this PR, and the user can run this again.
- the PR description lists merge prerequisites: an "Activation order", "Merge
  order", "Rollout", or "Depends on" section, or a link to a PR in another
  repository. Name each prerequisite and ask the user to confirm it is done;
  continue only after they confirm. Green CI or a linked PR having merged is not
  confirmation. Links to PRs in this repository alone are not prerequisites.

## Check unresolved review comments

Before marking the PR ready, enabling auto-merge, or merging directly, query
GitHub for this PR's review threads. Use the PR's repository and number with
`gh api graphql`; read `reviewThreads` with `id`, `isResolved`, and the first comment's `url`.
Fetch every page (for example, use `--paginate --slurp` with an `$endCursor`
variable and `pageInfo { hasNextPage endCursor }`). Inspect all returned pages
and require the final page to have `hasNextPage: false`. A failed query,
GraphQL errors, missing PR data, or incomplete pagination must stop the merge.
`gh pr view --comments`, review approval, and green checks do not establish that
all review threads are resolved.

If any thread has `isResolved: false`, stop and report each thread's link (or
its `id` and the PR URL if no comment link is available). Include outdated
threads; an outdated comment is not necessarily resolved. Do not resolve
threads, dismiss reviews, or change code as part of this acceptance. Leave the
workspace unfinished. If this check blocks merging for any reason and auto-merge
is already enabled, disable it with
`gh pr merge <number> --disable-auto` and confirm it is off; report any failure.
The user can run `worktree-done` again after the threads are resolved and any new
commits have been reviewed. General PR conversation comments have no resolved
state; this check uses GitHub's review-thread resolution state.

Run this check again immediately before each merge or auto-merge command below,
including direct-merge fallbacks after waiting for checks. This checks the state
at command time. GitHub can merge later after auto-merge is enabled; blocking
threads added after that point requires the repository to enforce conversation
resolution. Do not claim this skill enforces that server-side rule.

## Merge when checks pass

1. If the PR is a draft, mark it ready with `gh pr ready <number>`.
2. Run `gh pr merge <number> --auto --merge --match-head-commit <headRefOid>`. Use
   the repository's documented merge method instead of `--merge` when it has one.
   GitHub merges when the required checks pass, or at once if they already have.
3. If the command fails with `Pull request is in clean status`, GitHub refused to
   queue a PR that is already mergeable; auto-merge is not turned off. Recheck with
   `gh pr view <number> --json state,mergeable,mergeStateStatus,headRefOid,baseRefName`.
   If the PR is still open, `MERGEABLE`, `CLEAN`, at the accepted head, and on the
   same base, merge it directly with `gh pr merge <number> --merge --match-head-commit <headRefOid>`,
   using the same merge method as step 2. Otherwise report its state and stop.
4. If the repository has auto-merge turned off, report that and stop. Do not wait
   and merge manually; the user can merge through `worktree-cleanup` once checks
   pass.
5. Confirm the result with `gh pr view <number> --json state,autoMergeRequest`.
6. Once the PR has merged or auto-merge is on, mark this workspace done with
   `"$TOASTTY_CLI_PATH" action run workspace.set-done`; with no workspace given it
   marks the calling agent's own workspace. If the running Toastty does not list
   `workspace.set-done` in `action list`, or rejects it because this workspace is
   top-level rather than a task space, set the `task-status` annotation with text
   `DONE` and no URL instead, following the workspace annotation rules in the
   toastty-capabilities skill. Skip this when an earlier step stopped without
   merging or enabling auto-merge.

Report the PR, the accepted commit, and whether it merged or will merge when
checks pass. Mention that `worktree-cleanup` removes the workspace and worktree
after the merge. Keep the `github-pr` workspace chip; do not clear it when marking done.

`--match-head-commit` checks the head only when auto-merge is enabled. GitHub
keeps auto-merge on if someone with write access pushes later, so a later commit
would merge unreviewed. Push nothing to this branch while auto-merge is on.

## More work after acceptance

If the user asks for more changes before the PR merges, first run
`gh pr merge <number> --disable-auto` so the new commits cannot merge unreviewed.
Starting that work clears the workspace's done mark; also clear a `task-status`
annotation if step 6 set one.
Make the changes, verify them under repository rules, and ask the user to run
`worktree-done` again after reviewing the new version. If the PR already merged,
the follow-up work needs a new branch and PR.