docs: update Clownfish automerge skill

.agents/skills/clownfish-cloud-pr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clownfish-cloud-pr
-description: Use when launching Clownfish in GitHub Actions to create or update one guarded GitHub implementation PR from issue/PR refs, a ClawSweeper report, or a custom maintainer prompt.
+description: Use when launching Clownfish in GitHub Actions to create or update one guarded GitHub implementation PR from issue/PR refs, a ClawSweeper report, a custom maintainer prompt, or to opt an existing Clownfish PR into ClawSweeper-reviewed cloud automerge.
 ---
 
 # Clownfish Cloud PR
@@ -8,13 +8,35 @@ description: Use when launching Clownfish in GitHub Actions to create or update
 Use this skill when the user wants Codex to ask Clownfish to create a PR in the
 cloud from issue/PR refs plus a custom prompt.
 
-## Create One Job
+## Start
 
 ```bash
 cd ~/Projects/clownfish
 git status --short --branch
 gh variable list --repo openclaw/clownfish --json name,value \
   --jq 'map(select(.name|test("^CLOWNFISH_"))) | sort_by(.name) | .[] | {name,value}'
+```
+
+Keep merge gated unless Peter explicitly opens it. Execute/fix gates are closed
+unless the repo variables are literally `1`; normal fix-PR work needs an
+intentional execution window:
+
+```bash
+gh variable set CLOWNFISH_ALLOW_EXECUTE --repo openclaw/clownfish --body 1
+gh variable set CLOWNFISH_ALLOW_FIX_PR --repo openclaw/clownfish --body 1
+gh variable set CLOWNFISH_ALLOW_MERGE --repo openclaw/clownfish --body 0
+gh variable set CLOWNFISH_ALLOW_AUTOMERGE --repo openclaw/clownfish --body 0
+```
+
+Reset `CLOWNFISH_ALLOW_EXECUTE=0` and `CLOWNFISH_ALLOW_FIX_PR=0` after the
+window. If those vars are absent or not `1`, execute/autonomous workflow runs
+stay plan-only/no-mutation.
+
+## Create One Job
+
+From refs and a custom prompt:
+
+```bash
 npm run create-job -- \
   --repo openclaw/openclaw \
   --refs 123,456 \
@@ -30,7 +52,8 @@ npm run create-job -- \
 
 The script checks for an existing open PR/body match and remote branch named
 `clownfish/<cluster-id>` before writing a duplicate job. Use `--dry-run` to
-inspect the exact job body.
+inspect the exact job body and `--force` only after deciding the duplicate check
+is stale.
 
 ## Ask For A Replacement PR
 
@@ -68,18 +91,7 @@ npm run dispatch -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md \
 ```
 
 Do not use `--dispatch` until the job is committed and pushed; the workflow
-reads the job path from GitHub. Execute/fix gates are closed unless the repo
-variables are literally `1`; open them only for the execution window:
-
-```bash
-gh variable set CLOWNFISH_ALLOW_EXECUTE --repo openclaw/clownfish --body 1
-gh variable set CLOWNFISH_ALLOW_FIX_PR --repo openclaw/clownfish --body 1
-gh variable set CLOWNFISH_ALLOW_MERGE --repo openclaw/clownfish --body 0
-```
-
-Reset `CLOWNFISH_ALLOW_EXECUTE=0` and `CLOWNFISH_ALLOW_FIX_PR=0` after the
-window. Keep `CLOWNFISH_ALLOW_MERGE=0` unless Peter explicitly opens the merge
-gate.
+reads the job path from GitHub.
 
 ## Maintainer Comment Commands
 
@@ -94,6 +106,7 @@ Supported commands:
 /clownfish fix ci
 /clownfish address review
 /clownfish rebase
+/clownfish automerge
 /clownfish explain
 /clownfish stop
 @openclaw-clownfish fix ci
@@ -112,12 +125,47 @@ npm run comment-router -- --repo openclaw/openclaw --execute --wait-for-capacity
 Scheduled routing stays dry until `CLOWNFISH_COMMENT_ROUTER_EXECUTE=1` is set in
 `openclaw/clownfish` repo variables.
 
+## Bounded ClawSweeper-Reviewed Automerge
+
+Use this only for an existing Clownfish PR that maps back to a `clownfish/*`
+branch and job file:
+
+```text
+/clownfish automerge
+```
+
+The router verifies the commenter is a maintainer, adds
+`clownfish:automerge`, dispatches ClawSweeper for the current PR head, and
+waits for trusted ClawSweeper markers. `needs-changes` / `fix-required`
+dispatches the normal repair worker. `pass`, `approved`, or `no-changes` may
+merge only when the marker SHA matches the current PR head, checks are green,
+GitHub says the PR is mergeable, no `clownfish:human-review` label is present,
+and both merge gates are open:
+
+```bash
+gh variable set CLOWNFISH_ALLOW_MERGE --repo openclaw/clownfish --body 1
+gh variable set CLOWNFISH_ALLOW_AUTOMERGE --repo openclaw/clownfish --body 1
+```
+
+The actual merge command is pinned with GitHub's head-match guard, so a branch
+push after ClawSweeper reviewed cannot merge an unreviewed head. If either
+merge gate is closed when ClawSweeper passes, Clownfish labels the PR
+`clownfish:merge-ready` only after readiness checks have passed; failing checks,
+stale heads, conflicts, draft state, or human-review labels must not get that
+label. Pause with `/clownfish stop`, which adds `clownfish:human-review`.
+
+The repair loop is capped by `CLOWNFISH_CLAWSWEEPER_MAX_REPAIRS_PER_PR`
+(default `5`) and `CLOWNFISH_CLAWSWEEPER_MAX_REPAIRS_PER_HEAD` (default `1`).
+
 ## Guardrails
 
 - One cluster, one branch, one PR: `clownfish/<cluster-id>`.
 - No security-sensitive work.
 - New replacement PRs are capped per touched area by
   `CLOWNFISH_MAX_ACTIVE_PRS_PER_AREA`.
+- Do not merge from Clownfish unless Peter explicitly asks.
+- Do not open `CLOWNFISH_ALLOW_AUTOMERGE` unless Peter explicitly asks for an
+  automerge window.
 - Do not close duplicates before the fix PR path exists, lands, or is proven
   unnecessary.
 - Codex workers do not get GitHub tokens; deterministic scripts own writes.