@chris1807/claude-kit 2.1.58 → 2.1.59

package/README.md

@@ -331,7 +331,8 @@ Claude automatically:
 3. Creates a PR targeting the `staging` branch — merging it triggers the Staging pipeline
 4. Links all work items to the PR
 5. Asks who verifies each product group on Staging (`COM`, `PAY`, …) — candidates are the non-developer names already on those work items
-6. Watches the PR and the Staging pipeline; once it's green, moves the work items to `Staging` and assigns them to the approved verifiers
+6. Waits for Serena (the AI reviewer) to approve the PR, then completes it — for `dev`, `test`, and `staging` only; a `prod` PR you merge yourself
+7. Watches the Staging pipeline; once it's green, moves the work items to `Staging` and assigns them to the approved verifiers
 
 The same command walks a release through `test` → `staging` → `prod`; with no environment given it picks the next one.
 
@@ -341,7 +342,7 @@ The same command walks a release through `test` → `staging` → `prod`; with n
 /cherry-pick AB#1234 AB#1235 prod
 ```
 
-Cherry-picks specific work items to an environment without a formal release. Same gate check, same verifier question, and the same automatic state advance + assignment once the pipeline is green as `/deploy-release`. `main` is also a valid target — that's how a hot fix that went straight to `prod` is brought back into the compare branch.
+Cherry-picks specific work items to an environment without a formal release. Same gate check, same verifier question, and the same automatic state advance + assignment once the pipeline is green as `/deploy-release`. Targeting `dev`, `test`, or `staging` it also merges the PR itself once Serena approves it; a `prod` PR waits for a person. `main` is also a valid target — that's how a hot fix that went straight to `prod` is brought back into the compare branch.
 
 ### Promote an Environment
 
@@ -351,7 +352,7 @@ Cherry-picks specific work items to an environment without a formal release. Sam
 /promote                  ← auto-detects from the current branch
 ```
 
-Creates a PR to promote all code from one branch to the next in the chain (`main → dev → test → staging → prod`). Shows every commit and work item before confirming, gate-checks the work items, asks who verifies each product group, and advances and assigns them once the merge's pipeline is green. `main → dev` is the usual first hop after feature PRs merge — nothing has deployed before that.
+Creates a PR to promote all code from one branch to the next in the chain (`main → dev → test → staging → prod`). Shows every commit and work item before confirming, gate-checks the work items, asks who verifies each product group, and advances and assigns them once the merge's pipeline is green. Below production it also **merges the PR for you**: it polls until Serena (the AI reviewer) approves, then completes it with autocomplete — a PR into `prod` is always merged by a person. `main → dev` is the usual first hop after feature PRs merge — nothing has deployed before that.
 
 ### Rollback a Deployment
 
@@ -509,7 +510,7 @@ The PR merges into `main`. **That merge deploys nothing** — `main` is the comp
 /promote main dev
 ```
 
-Merge that PR. Claude asks who verifies each product group on Dev, watches the Dev pipeline, and once it's green moves the work items to `Ready for Testing` and assigns them to those people.
+Claude asks who verifies each product group on Dev, waits for Serena to approve the PR and merges it, watches the Dev pipeline, and once it's green moves the work items to `Ready for Testing` and assigns them to those people. (Dev, Test, and Staging merge themselves this way; a production PR you merge yourself.)
 
 ### Step 2: Deploy Changes (Quick Commits)
 
@@ -569,7 +570,7 @@ When stakeholders have verified on Staging and set the items to `Ready to Deploy
 /deploy-release 23 prod
 ```
 
-Same process — gate `Ready to Deploy`, cherry-picks from `staging` into a PR targeting `prod`. After merge the Production CD pipeline triggers; when it comes back green the items move to `Deployed` and are assigned to whoever you named for each product group.
+Same process — gate `Ready to Deploy`, cherry-picks from `staging` into a PR targeting `prod`. **You merge this one** — Claude auto-merges only into `dev`, `test`, and `staging`. After merge the Production CD pipeline triggers; when it comes back green the items move to `Deployed` and are assigned to whoever you named for each product group.
 
 ### Selective Deployment
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.58",
+  "version": "2.1.59",
   "description": "Claude Code starter kit for Azure DevOps teams — agents, hooks, MCP servers, slash commands, and end-to-end work item → PR → release → deploy workflow automation",
   "type": "module",
   "bin": {

package/templates/commands/cherry-pick.md

@@ -162,9 +162,19 @@ Approve? (yes / change)
 
 `change` re-asks 6c. Only after `yes` do you move on — if the PR merges before the user answers, keep waiting for the answer, then run Step 8.
 
-## Step 7: Watch the Merge, Then the Pipeline
+## Step 7: Get the PR Merged, Then Watch the Pipeline
 
-Do NOT merge the PR yourself — a reviewer approves and completes it. Report the PR, then watch for the deployment:
+### 7a. Who completes the PR depends on the target
+
+| Target | Who merges |
+|---|---|
+| `dev`, `test`, `staging` | **You do** — poll until Serena approves, then complete the PR (7b–7c) |
+| `prod` | A human. **Never auto-merge into production.** |
+| `main` | A human. No pipeline and no state change either — report the PR and stop. |
+
+Resolve the target through the Pipeline Configuration table, not by the spelling of the branch — a project whose staging branch is named `Staging` or `release/staging` is still staging, and a project with no `test` row simply has no test hop.
+
+Report the PR either way:
 
 ```
 Cherry-pick PR created for {environment}.
@@ -174,13 +184,88 @@ Work items:
 - AB#1234: COM - Add payment export
 - AB#1240: PAY - Fix login redirect
 
-Merging the PR triggers the CD pipeline for {environment}. I'm watching the PR
-and that pipeline — when it comes back green I'll set these {count} items to
-`{state after merge}` and assign them as approved above. Nothing is written
-until then. Say `stop watching` to leave the states alone.
+{merge line}
 ```
 
-1. **Wait for the PR to complete.** Poll `repo_pull_request` until `status` is `completed`; note the merge commit and completion time. `abandoned` → stop, change nothing, report it.
+`{merge line}` for `dev` / `test` / `staging`:
+
+```
+Waiting on Serena's review. When she approves I'll complete the PR, which
+triggers the {environment} CD pipeline; when that comes back green I'll set
+these {count} items to `{state after merge}` and assign them as approved
+above. Say `don't merge` to stop before the merge, or `stop watching` to
+leave the work item states alone.
+```
+
+`{merge line}` for `prod` / `main`:
+
+```
+A reviewer approves and completes this one — I don't merge into {environment}.
+I'm watching the PR and that pipeline: when it comes back green I'll set these
+{count} items to `{state after merge}` and assign them as approved above.
+Nothing is written until then. Say `stop watching` to leave the states alone.
+```
+
+### 7b. Wait for Serena's approval (`dev` / `test` / `staging` only)
+
+Serena is the AI reviewer on this org's pull requests. Find her among the PR's reviewers by matching `serena` case-insensitively against `displayName` / `uniqueName` — never hardcode an identity id, and never count another reviewer's approval as hers.
+
+Reviewer votes: `10` approved · `5` approved with suggestions · `0` no vote yet · `-5` waiting for author · `-10` rejected.
+
+- `10` or `5` → approved. Go to 7c.
+- `-5` or `-10` → **do not merge.** List her threads (`repo_pull_request_thread` `action: list`), report what she flagged, and stop. `/resolve-feedback {pr-id}` addresses them; her vote is re-evaluated after the next push.
+- `0`, or she is not on the reviewer list yet → keep polling.
+
+**Never cast a vote on the PR yourself** to satisfy an approval policy, and never add yourself as a reviewer to do it.
+
+Poll in the background — never a foreground `sleep`:
+
+```bash
+ORG=<org-url>; PR=<pr-id>; TRIES=0
+while [ $TRIES -lt 120 ]; do
+  VOTE=$(az repos pr show --id "$PR" --org "$ORG" \
+           --query "reviewers[].[displayName,vote]" -o tsv \
+         | grep -i serena | cut -f2 | head -1)
+  case "$VOTE" in
+    10|5)   echo "APPROVED vote=$VOTE"; break ;;
+    -5|-10) echo "BLOCKED  vote=$VOTE"; break ;;
+    *)      TRIES=$((TRIES + 1)); sleep 30 ;;
+  esac
+done
+[ $TRIES -ge 120 ] && echo "TIMEOUT - no Serena vote after 60 minutes"
+```
+
+Run it with `Monitor` (or Bash `run_in_background`). An empty `VOTE` means she isn't a reviewer yet, which is why the loop keeps going rather than treating it as a decision. Without the Azure CLI, poll `repo_pull_request` `action: get` on the same ~30-second cadence and read `reviewers[]`.
+
+If the loop times out, leave the PR open and ask whether to keep waiting or merge without her. **If she was never added as a reviewer at all, say exactly that** — it usually means the PR was never picked up for review, not that it sailed through.
+
+### 7c. Complete the PR
+
+Merge with `repo_pull_request_write` `action: update`:
+
+| Field | Value | Why |
+|---|---|---|
+| `autoComplete` | `true` | ADO completes it the moment the remaining branch policies pass — a required build still gates the merge |
+| `mergeStrategy` | `NoFastForward` | one merge commit, cherry-pick history intact |
+| `transitionWorkItems` | `false` | **required.** This command owns the work item states (Step 8); ADO's own transition moves parents too |
+| `deleteSourceBranch` | `true` | the `cherry-pick/...` branch is disposable |
+| `bypassPolicy` | **never set it** | a policy that isn't passing is a stop, not an obstacle |
+
+Then poll `repo_pull_request` `action: get` until `status` is `completed`. If it stays `Active` with autocomplete queued, a branch policy is unmet — report which one and stop; do not bypass it and do not push to the source branch to force it.
+
+CLI fallback if the MCP update fails:
+
+```bash
+az repos pr update --id <pr-id> --org <org-url> \
+  --auto-complete true --transition-work-items false --delete-source-branch true \
+  --merge-commit-message "Cherry-pick AB#1234, AB#1240 -> {Environment}"
+```
+
+If the user said `don't merge`, leave the PR open, say so, and skip to 7d — a human merging it later still gets the pipeline watch and the state changes.
+
+### 7d. Watch the CD pipeline
+
+1. **Confirm the PR completed.** Poll `repo_pull_request` until `status` is `completed`; note the merge commit and completion time. `abandoned` → stop, change nothing, report it.
 2. **Find the CD run.** Look up the target branch's pipeline ID(s) in the Pipeline Configuration table, then poll `pipelines_build` for runs on `refs/heads/<target-branch>` queued at or after the merge time — match the merge commit when the run exposes it — and **capture each run's id**. A run that was already completed before the merge is not this deployment; ignore it. A branch with more than one pipeline (API + Client) must have **all** of them green.
 3. **Wait for a terminal result** on each run: `succeeded`, `partiallySucceeded`, `failed`, or `canceled`.
 

package/templates/commands/deploy-release.md

@@ -217,9 +217,20 @@ Approve? (yes / change)
 
 `change` re-asks 8c. Only after `yes` do you move on — if the PR merges before the user answers, keep waiting for the answer, then run Step 10.
 
-## Step 9: Watch the Merge, Then the Pipeline
+## Step 9: Get the PR Merged, Then Watch the Pipeline
 
-Do NOT merge the PR yourself, and do NOT trigger the CD pipeline — it triggers on the merge. Report the PR, then watch for the deployment:
+Never trigger the CD pipeline by hand — it triggers on the merge.
+
+### 9a. Who completes the PR depends on the target
+
+| Target | Who merges |
+|---|---|
+| `dev`, `test`, `staging` | **You do** — poll until Serena approves, then complete the PR (9b–9c) |
+| `prod` | A human. **Never auto-merge into production.** |
+
+Resolve the target through the Pipeline Configuration table, not by the spelling of the branch — a project whose staging branch is named `Staging` or `release/staging` is still staging, and a project with no `test` row simply has no test hop.
+
+Report the PR either way:
 
 ```
 Release #{N} PR created for {environment}.
@@ -232,13 +243,89 @@ Work items included:
 - AB#1236: COM - View history
 - AB#1240: PAY - Fix login redirect
 
-Review and approve the PR — merging it triggers the CD pipeline for {environment}.
-I'm watching the PR and that pipeline; when it comes back green I'll set these
+{merge line}
+```
+
+`{merge line}` for `dev` / `test` / `staging`:
+
+```
+Waiting on Serena's review. When she approves I'll complete the PR, which
+triggers the {environment} CD pipeline; when that comes back green I'll set
+these {count} items to `{state after merge}` and assign them as approved
+above. Say `don't merge` to stop before the merge, or `stop watching` to
+leave the work item states alone.
+```
+
+`{merge line}` for `prod`:
+
+```
+Review and approve the PR — a person merges this one; I don't merge into
+production. Merging it triggers the CD pipeline for {environment}. I'm
+watching the PR and that pipeline; when it comes back green I'll set these
 {count} items to `{state after merge}` and assign them as approved above.
 Nothing is written until then. Say `stop watching` to leave the states alone.
 ```
 
-1. **Wait for the PR to complete.** Poll `repo_pull_request` until `status` is `completed`; note the merge commit and completion time. `abandoned` → stop, change nothing, report it.
+### 9b. Wait for Serena's approval (`dev` / `test` / `staging` only)
+
+Serena is the AI reviewer on this org's pull requests. Find her among the PR's reviewers by matching `serena` case-insensitively against `displayName` / `uniqueName` — never hardcode an identity id, and never count another reviewer's approval as hers.
+
+Reviewer votes: `10` approved · `5` approved with suggestions · `0` no vote yet · `-5` waiting for author · `-10` rejected.
+
+- `10` or `5` → approved. Go to 9c.
+- `-5` or `-10` → **do not merge.** List her threads (`repo_pull_request_thread` `action: list`), report what she flagged, and stop. A release branch is a cherry-pick of commits that already merged upstream, so the fix usually belongs on the source branch and comes forward in the next release — not as a patch commit on `release/{N}-to-{environment}`.
+- `0`, or she is not on the reviewer list yet → keep polling.
+
+**Never cast a vote on the PR yourself** to satisfy an approval policy, and never add yourself as a reviewer to do it.
+
+Poll in the background — never a foreground `sleep`:
+
+```bash
+ORG=<org-url>; PR=<pr-id>; TRIES=0
+while [ $TRIES -lt 120 ]; do
+  VOTE=$(az repos pr show --id "$PR" --org "$ORG" \
+           --query "reviewers[].[displayName,vote]" -o tsv \
+         | grep -i serena | cut -f2 | head -1)
+  case "$VOTE" in
+    10|5)   echo "APPROVED vote=$VOTE"; break ;;
+    -5|-10) echo "BLOCKED  vote=$VOTE"; break ;;
+    *)      TRIES=$((TRIES + 1)); sleep 30 ;;
+  esac
+done
+[ $TRIES -ge 120 ] && echo "TIMEOUT - no Serena vote after 60 minutes"
+```
+
+Run it with `Monitor` (or Bash `run_in_background`). An empty `VOTE` means she isn't a reviewer yet, which is why the loop keeps going rather than treating it as a decision. Without the Azure CLI, poll `repo_pull_request` `action: get` on the same ~30-second cadence and read `reviewers[]`.
+
+If the loop times out, leave the PR open and ask whether to keep waiting or merge without her. **If she was never added as a reviewer at all, say exactly that** — it usually means the PR was never picked up for review, not that it sailed through.
+
+### 9c. Complete the PR
+
+Merge with `repo_pull_request_write` `action: update`:
+
+| Field | Value | Why |
+|---|---|---|
+| `autoComplete` | `true` | ADO completes it the moment the remaining branch policies pass — a required build still gates the merge |
+| `mergeStrategy` | `NoFastForward` | one merge commit, cherry-pick history intact |
+| `transitionWorkItems` | `false` | **required.** This command owns the work item states (Step 10); ADO's own transition moves parents too |
+| `deleteSourceBranch` | `true` | the `release/{N}-to-{environment}` branch is disposable — the release itself lives in the iteration and the `release-{N}` tags |
+| `bypassPolicy` | **never set it** | a policy that isn't passing is a stop, not an obstacle |
+
+Then poll `repo_pull_request` `action: get` until `status` is `completed`. If it stays `Active` with autocomplete queued, a branch policy is unmet — report which one and stop; do not bypass it and do not push to the source branch to force it.
+
+CLI fallback if the MCP update fails:
+
+```bash
+az repos pr update --id <pr-id> --org <org-url> \
+  --auto-complete true --transition-work-items false --delete-source-branch true \
+  --merge-commit-message "Release #{N} -> {Environment}"
+```
+
+If the user said `don't merge`, leave the PR open, say so, and skip to 9d — a human merging it later still gets the pipeline watch and the state changes.
+
+### 9d. Watch the CD pipeline
+
+1. **Confirm the PR completed.** Poll `repo_pull_request` until `status` is `completed`; note the merge commit and completion time. `abandoned` → stop, change nothing, report it.
 2. **Find the CD run.** Look up the target branch's pipeline ID(s) in the Pipeline Configuration table, then poll `pipelines_build` for runs on `refs/heads/<target-branch>` queued at or after the merge time — match the merge commit when the run exposes it — and **capture each run's id**. A run that was already completed before the merge is not this deployment; ignore it. A branch with more than one pipeline (API + Client) must have **all** of them green.
 3. **Wait for a terminal result** on each run: `succeeded`, `partiallySucceeded`, `failed`, or `canceled`.
 

package/templates/commands/promote.md

@@ -159,9 +159,18 @@ Approve? (yes / change)
 
 `change` re-asks 5c. Only after `yes` do you move on — if the PR merges before the user answers, keep waiting for the answer, then run Step 7.
 
-## Step 6: Watch the Merge, Then the Pipeline
+## Step 6: Get the PR Merged, Then Watch the Pipeline
 
-Do NOT merge the PR yourself — a reviewer approves and completes it. Report the PR, then watch for the deployment:
+### 6a. Who completes the PR depends on the target
+
+| Target | Who merges |
+|---|---|
+| `dev`, `test`, `staging` | **You do** — poll until Serena approves, then complete the PR (6b–6c) |
+| `prod` | A human. **Never auto-merge into production.** |
+
+Resolve the target through the Pipeline Configuration table, not by the spelling of the branch — a project whose staging branch is named `Staging` or `release/staging` is still staging, and a project with no `test` row simply has no test hop.
+
+Report the PR either way:
 
 ```
 Promotion PR created: {source} → {target}
@@ -169,13 +178,88 @@ Promotion PR created: {source} → {target}
 PR: {pr-url}
 
 {count} commits, {n} work items included.
-Merging the PR triggers the CD pipeline for {target}. I'm watching the PR and
-that pipeline — when it comes back green I'll set the {n} work items to
-`{state after merge}` and assign them as approved above. Nothing is written
-until then. Say `stop watching` to leave the states alone.
+{merge line}
+```
+
+`{merge line}` for `dev` / `test` / `staging`:
+
+```
+Waiting on Serena's review. When she approves I'll complete the PR, which
+triggers the {target} CD pipeline; when that comes back green I'll set the
+{n} work items to `{state after merge}` and assign them as approved above.
+Say `don't merge` to stop before the merge, or `stop watching` to leave the
+work item states alone.
+```
+
+`{merge line}` for `prod`:
+
+```
+A reviewer approves and completes this one — I don't merge into production.
+I'm watching the PR and that pipeline: when it comes back green I'll set the
+{n} work items to `{state after merge}` and assign them as approved above.
+Nothing is written until then. Say `stop watching` to leave the states alone.
+```
+
+### 6b. Wait for Serena's approval (`dev` / `test` / `staging` only)
+
+Serena is the AI reviewer on this org's pull requests. Find her among the PR's reviewers by matching `serena` case-insensitively against `displayName` / `uniqueName` — never hardcode an identity id, and never count another reviewer's approval as hers.
+
+Reviewer votes: `10` approved · `5` approved with suggestions · `0` no vote yet · `-5` waiting for author · `-10` rejected.
+
+- `10` or `5` → approved. Go to 6c.
+- `-5` or `-10` → **do not merge.** List her threads (`repo_pull_request_thread` `action: list`), report what she flagged, and stop. On a promotion the fix belongs on the source branch, not on the PR — a promotion PR has no branch of its own to push to.
+- `0`, or she is not on the reviewer list yet → keep polling.
+
+**Never cast a vote on the PR yourself** to satisfy an approval policy, and never add yourself as a reviewer to do it.
+
+Poll in the background — never a foreground `sleep`:
+
+```bash
+ORG=<org-url>; PR=<pr-id>; TRIES=0
+while [ $TRIES -lt 120 ]; do
+  VOTE=$(az repos pr show --id "$PR" --org "$ORG" \
+           --query "reviewers[].[displayName,vote]" -o tsv \
+         | grep -i serena | cut -f2 | head -1)
+  case "$VOTE" in
+    10|5)   echo "APPROVED vote=$VOTE"; break ;;
+    -5|-10) echo "BLOCKED  vote=$VOTE"; break ;;
+    *)      TRIES=$((TRIES + 1)); sleep 30 ;;
+  esac
+done
+[ $TRIES -ge 120 ] && echo "TIMEOUT - no Serena vote after 60 minutes"
 ```
 
-1. **Wait for the PR to complete.** Poll `repo_pull_request` until `status` is `completed`; note the merge commit and the completion time. `abandoned` → stop, change nothing, report it.
+Run it with `Monitor` (or Bash `run_in_background`). An empty `VOTE` means she isn't a reviewer yet, which is why the loop keeps going rather than treating it as a decision. Without the Azure CLI, poll `repo_pull_request` `action: get` on the same ~30-second cadence and read `reviewers[]`.
+
+If the loop times out, leave the PR open and ask whether to keep waiting or merge without her. **If she was never added as a reviewer at all, say exactly that** — it usually means the PR was never picked up for review, not that it sailed through.
+
+### 6c. Complete the PR
+
+Merge with `repo_pull_request_write` `action: update`:
+
+| Field | Value | Why |
+|---|---|---|
+| `autoComplete` | `true` | ADO completes it the moment the remaining branch policies pass — a required build still gates the merge |
+| `mergeStrategy` | `NoFastForward` | one merge commit; never squash a promotion — it rewrites the commit ids the next hop cherry-picks by |
+| `transitionWorkItems` | `false` | **required.** This command owns the work item states (Step 7); ADO's own transition moves parents too |
+| `deleteSourceBranch` | **`false`** | the source is a long-lived environment branch (`main`, `dev`, `test`, `staging`) — deleting it would destroy the promotion chain |
+| `bypassPolicy` | **never set it** | a policy that isn't passing is a stop, not an obstacle |
+
+Then poll `repo_pull_request` `action: get` until `status` is `completed`. If it stays `Active` with autocomplete queued, a branch policy is unmet — report which one and stop; do not bypass it and do not push to the source branch to force it.
+
+CLI fallback if the MCP update fails:
+
+```bash
+az repos pr update --id <pr-id> --org <org-url> \
+  --auto-complete true --transition-work-items false --delete-source-branch false \
+  --merge-commit-message "Promote {source} -> {target}"
+```
+
+If the user said `don't merge`, leave the PR open, say so, and skip to 6d — a human merging it later still gets the pipeline watch and the state changes.
+
+### 6d. Watch the CD pipeline
+
+1. **Confirm the PR completed.** Poll `repo_pull_request` until `status` is `completed`; note the merge commit and the completion time. `abandoned` → stop, change nothing, report it.
 2. **Find the CD run.** Look up the target branch's pipeline ID(s) in the Pipeline Configuration table, then poll `pipelines_build` for runs on `refs/heads/<target-branch>` queued at or after the merge time — match the merge commit when the run exposes it — and **capture each run's id**. A run that was already completed before the merge is not this deployment; ignore it. A branch with more than one pipeline (API + Client) must have **all** of them green.
 3. **Wait for a terminal result** on each run: `succeeded`, `partiallySucceeded`, `failed`, or `canceled`.
 

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -102,7 +102,7 @@ Claude maintains persistent memory across sessions in `~/.claude/projects/.../me
 4. **PR merges** into `main` — the compare branch. **Nothing deploys yet.** The work item stays in `Code Review` until it is promoted
 5. **Promote or release** — `/promote main dev` carries everything on `main` to Dev; `/create-release <N>` groups work items so `/deploy-release <N> test` → `staging` → `prod` can carry just those
 6. **Say who verifies** — before the merge, the command asks who each product group (`COM`, `PAY`, …) should be assigned to in the target environment, offering the non-developer names already on those work items
-7. **Merge each promotion PR** — that merge triggers the environment's CD pipeline. The command watches it and, once it's green, sets the work items to `Testing`, `Staging`, or `Deployed` **and** assigns them to the approved verifiers — automatically, no reply needed
+7. **The promotion PR merges** — for `dev`, `test`, and `staging`, the deploy commands wait for Serena to approve and then complete the PR themselves; a `prod` PR is always merged by a person. That merge triggers the environment's CD pipeline. The command watches it and, once it's green, sets the work items to `Testing`, `Staging`, or `Deployed` **and** assigns them to the approved verifiers — automatically, no reply needed
 8. **Test** using Playwright MCP for browser testing
 9. **Track** work items via the Azure DevOps MCP server
 10. **Learn** — Claude saves what worked for next time
@@ -179,6 +179,7 @@ How the commands use this table:
 
 - **Gate check before the PR.** `/deploy-release`, `/cherry-pick`, and `/promote` compare each carried work item's state against the gate for the target environment. Anything behind the gate (e.g. still `Testing` when deploying to `staging`) is flagged and the user decides whether to include it. Items *ahead* of the gate (e.g. already `Deployed` on a cherry-pick to `prod`) are reported and left alone.
 - **Advance on a green pipeline, automatically.** `/promote`, `/cherry-pick`, and `/deploy-release` do not stop at the PR. They poll it until it is `completed`, then poll the target branch's CD pipeline until every run finishes. Only on `succeeded` do they write the new state — for every carried User Story, Bug, and Hot Fix, never a Feature or Task, and never backward. A failed or canceled run changes **nothing** and is reported with the log link. `/track` reports items whose state lags the branch their commits are on and offers to catch them up.
+- **Auto-merge below production.** When the target is `dev`, `test`, or `staging`, all three commands poll the PR until **Serena** (the AI reviewer) votes, then complete it with autocomplete — remaining branch policies still gate the merge, work item transitions are left off so the command's own state logic owns them, and a branch policy that isn't passing is a stop, never a bypass. A rejection or *waiting for author* vote stops the merge and reports her threads. A PR into `prod` (or into `main`) is **always** merged by a person.
 - **Assign the verifier at the same time.** The state change hands the item to a person, so the same three commands ask **before the merge** who each group of items should go to, then apply the assignee alongside the state once the pipeline is green. See **Verifier Assignment** below.
 - **Never assume the state list.** Confirm with `mcp__azure-devops__wit_work_item` (`action: get_type`) on an unfamiliar project before writing a state name — a bad name is accepted silently by a query and rejected only at write time.
 
@@ -207,7 +208,7 @@ This creates a `Release #23` iteration, assigns the selected work items to it, a
 /deploy-release 23 staging
 /deploy-release 23 prod
 ```
-This finds all work items in Release #23, checks each one against the target environment's gate state, cherry-picks their commits into a release branch (`release/23-to-staging`), creates a PR targeting the environment branch, links all work items, asks who verifies each product group, and — once the merge's CD pipeline comes back green — advances them to the environment's state (`Testing`, `Staging`, `Deployed`) and assigns them to those verifiers.
+This finds all work items in Release #23, checks each one against the target environment's gate state, cherry-picks their commits into a release branch (`release/23-to-staging`), creates a PR targeting the environment branch, links all work items, asks who verifies each product group, merges the PR once Serena approves it (`dev`/`test`/`staging` only — a `prod` PR waits for a person), and — once the merge's CD pipeline comes back green — advances them to the environment's state (`Testing`, `Staging`, `Deployed`) and assigns them to those verifiers.
 
 **Selective deployment:** Since releases are deployed via cherry-pick, you can deploy a full release or a subset. If staging has 5 user stories but only 3 are `Ready to Deploy`, create a release with just those 3 and deploy it.
 
@@ -227,7 +228,7 @@ Cherry-pick specific work items to an environment without a formal release:
 ```
 /cherry-pick AB#1234 AB#1235 prod
 ```
-This finds commits for the specified work items, checks them against the target's gate state, cherry-picks them into a branch (`cherry-pick/<date>-to-<environment>`), creates a PR, asks who verifies each product group, and — once the merge's CD pipeline is green — advances and assigns the work items.
+This finds commits for the specified work items, checks them against the target's gate state, cherry-picks them into a branch (`cherry-pick/<date>-to-<environment>`), creates a PR, asks who verifies each product group, merges the PR once Serena approves it (`dev`/`test`/`staging` only — a `prod` PR waits for a person), and — once the merge's CD pipeline is green — advances and assigns the work items.
 
 #### Promoting Environments
 
@@ -237,7 +238,7 @@ Promote all code from one environment to the next:
 /promote staging prod
 /promote                      ← auto-detects source and target from current branch
 ```
-This creates a PR from the source branch to the target branch with a summary of all included commits and their work items, checks the work items against the target's gate state, asks who verifies each product group, and — once the merge's CD pipeline is green — advances and assigns them. `main → dev` is the usual first hop after feature PRs merge.
+This creates a PR from the source branch to the target branch with a summary of all included commits and their work items, checks the work items against the target's gate state, asks who verifies each product group, merges the PR once Serena approves it (`dev`/`test`/`staging` only — a `prod` PR waits for a person), and — once the merge's CD pipeline is green — advances and assigns them. `main → dev` is the usual first hop after feature PRs merge.
 
 #### Rollbacks
 
@@ -302,10 +303,10 @@ All deployment and release operations are available as slash commands:
 | `/resolve-feedback` | `/resolve-feedback 142` | Address unresolved PR comment threads, push fixes, reply + resolve threads |
 | `/deploy` | `/deploy "commit message"` | Commit, push, trigger pipeline (only on `dev`/`test`/`staging`/`prod` — never on `main`) |
 | `/create-release` | `/create-release 23` | Group work items into Release #23 |
-| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → cherry-pick release to environment → PR → ask who verifies → advance + assign on a green pipeline |
+| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → cherry-pick release to environment → PR → ask who verifies → merge on Serena's approval (below prod) → advance + assign on a green pipeline |
 | `/add-to-release` | `/add-to-release 24 AB#4599` | Add work items to existing release |
-| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → cherry-pick specific work items → PR → ask who verifies → advance + assign on a green pipeline |
-| `/promote` | `/promote main dev` | Promote all code between environments (`main → dev → test → staging → prod`) → ask who verifies → advance + assign on a green pipeline |
+| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → cherry-pick specific work items → PR → ask who verifies → merge on Serena's approval (below prod) → advance + assign on a green pipeline |
+| `/promote` | `/promote main dev` | Promote all code between environments (`main → dev → test → staging → prod`) → ask who verifies → merge on Serena's approval (below prod) → advance + assign on a green pipeline |
 | `/rollback` | `/rollback AB#1234 prod` | Revert commits on an environment |
 | `/track` | `/track release 24` | Check release, pipeline, environment, or work item status; flags work items whose state lags their environment |
 | `/where` | `/where AB#1234` | Show which environment branches contain a work item's commits |