From 1684e9c17eb45e0551efe2b0a8b666efbdbc41ad Mon Sep 17 00:00:00 2001
From: NagyVikt <nagy.viktordp@gmail.com>
Date: Thu, 23 Apr 2026 21:50:18 +0200
Subject: [PATCH] docs(AGENTS): make Claude finish always include via-pr +
 wait-for-merge + cleanup

Previous contract already listed the four flags in prose but allowed the
reader to stop at bare `--via-pr`. This session demonstrated the failure
mode: a PR merged before a follow-up commit pushed, stranding the commit
on a local agent branch.

Changes:
- Switch the step-3 example's `--base dev` to `--base main` (this repo's
  default base) so the recipe runs verbatim.
- Add a "Default Claude finish (non-negotiable)" subsection that:
  - Requires all four flags unless the user opts out.
  - Shows the `gh pr merge <N> --auto --squash` follow-on for
    branch-protected repos.
  - Documents `GUARDEX_FINISH_MERGE_TIMEOUT` for slow CI.
  - Points to `gx finish --all` for sweeping multiple lanes.
  - Captures the `git worktree remove --force` recovery recipe when a
    source-probe temp worktree holds an agent branch.
---
 AGENTS.md | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 2a59f53..fdb294b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -160,11 +160,45 @@ gx branch start "refactor-payment-pipeline" "claude-name"
    ```bash
    gx branch finish \
      --branch "agent/claude-<name>/<slug>" \
-     --base dev --via-pr --wait-for-merge --cleanup
+     --base main --via-pr --wait-for-merge --cleanup
    ```
 
    Runs the OpenSpec tasks gate, merge-quality gate, and worktree prune — identical to the Codex path.
 
+#### Default Claude finish (non-negotiable)
+
+Claude's default completion command **must** include all four flags in this order: `--via-pr --wait-for-merge --cleanup`. Never stop at bare `--via-pr`; that strands commits and leaves worktrees dirty (see the stalled-worktree recovery section). The only time to deviate is when the user explicitly asks to keep the lane open (e.g. "don't merge yet", "leave the branch").
+
+When branch protection blocks a direct merge, enable auto-merge as soon as the PR URL is known so `--wait-for-merge` can observe the state transition:
+
+```bash
+# finish also prints the PR URL / number; use it immediately:
+gh pr merge <PR-NUMBER> --repo <owner>/<repo> --auto --squash
+```
+
+If checks are slow, extend the poll window rather than dropping the flag:
+
+```bash
+GUARDEX_FINISH_MERGE_TIMEOUT=3600 \
+  gx branch finish \
+    --branch "agent/claude-<name>/<slug>" \
+    --base main --via-pr --wait-for-merge --cleanup
+```
+
+One-shot sweep for multiple finished lanes:
+
+```bash
+gx finish --all       # iterates every agent/* branch the current user owns
+```
+
+If `gx branch finish --cleanup` reports a worktree held by a `__source-probe-*` temp path, recover with:
+
+```bash
+git worktree remove --force .omc/agent-worktrees/agent__claude__<slug>
+git worktree prune
+git branch -D agent/claude/<slug>
+```
+
 Notes:
 
 - Slash commands `/opsx:*` in `.claude/commands/opsx/` drive the OpenSpec artifact flow.