@chris1807/claude-kit 2.1.58 → 2.2.0

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.2.0",
   "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

@@ -33,6 +33,37 @@ Fetch each work item from Azure DevOps via MCP. Compare each one's `System.State
 Cherry-pick {count} work items to {environment}? Items behind the gate: include / drop / cancel
 ```
 
+### Step 1b: Scripts That Have to Be Run
+
+A deployment script — a SQL migration, a data backfill, a PowerShell step — is attached to the work item it belongs to, and it has to run in **every** environment that item's code lands in. A promotion carries the code; it does not carry the script, and nothing in the PR says one exists. That is how an environment ends up half-deployed.
+
+Fetch each carried work item with its attachments — `wit_work_item` `action: get`, `expand: "Relations"`, one call per item (`get_batch` has no `expand`) — and keep every relation whose `rel` is `AttachedFile` and whose filename extension is **not** a document, image or video:
+
+```
+.xlsx .xls .xlsm .xlsb .csv  .docx .doc .docm  .pdf
+.png .jpg .jpeg .gif .bmp .ico .svg .webp .tiff .tif
+.mp4 .mov .avi .webm .mkv .wmv .flv .m4v
+```
+
+Everything else counts, extensionless files included. The rule is deliberately loose, because the two mistakes do not cost the same: a filename someone glances at and dismisses costs seconds, a migration nobody ran costs an environment.
+
+Show them with the table above, before the confirmation:
+
+```
+📜 Scripts to run with this promotion:
+
+| Work Item | Script |
+|-----------|--------|
+| AB#1234 | 2026-09-11_add_delivery_index.sql |
+| AB#1240 | backfill-tenant-flags.ps1 |
+
+Download them from the work items. This command does not run them.
+```
+
+If nothing carries an attachment, say `No deployment scripts attached` on one line and move on.
+
+**Reported, never enforced.** A script does not block the promotion and does not change the gate check: the attachment may already have been run, may be a reference copy, may not be a script at all. Listing it is the whole job — the person deploying decides.
+
 Wait for confirmation. `drop` removes flagged items from this cherry-pick only.
 
 ## Step 2: Find Commits
@@ -91,7 +122,7 @@ Cherry-picking:
    - **sourceRefName**: `refs/heads/cherry-pick/<date>-to-<environment>`
    - **targetRefName**: `refs/heads/<target-environment-branch>`
    - **title**: `Cherry-pick AB#1234, AB#1235 → {Environment}`
-   - **description**: List all work items with IDs and titles
+   - **description**: List all work items with IDs and titles, and — under a `Scripts to run` heading — any deployment scripts found in Step 1b, so whoever merges sees them without opening the work items
 3. Link all work items to the PR via `wit_link_work_item_to_pull_request`
 
 ## Step 6: Pick Who Verifies Each Group (before the merge)
@@ -162,9 +193,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
+
+### 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.
 
-Do NOT merge the PR yourself — a reviewer approves and completes it. Report the PR, then watch for the deployment:
+Report the PR either way:
 
 ```
 Cherry-pick PR created for {environment}.
@@ -174,13 +215,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}
+```
+
+`{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)
 
-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.
+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`.
 
@@ -234,3 +350,10 @@ Next: {the human step — "QA tests on Test and sets Ready for Staging" / "stake
 ```
 
 If the user said `stop watching`, or an update fails, leave the rest alone, say exactly which items were and were not updated, and note that `/track` will flag the lag later.
+
+If any carried item had a deployment script (Step 1b), repeat it here — this is the moment it has to run, and the list is stale in the scroll-back by now:
+
+```
+📜 Still to run on {environment}: AB#1234 2026-09-11_add_delivery_index.sql, AB#1240 backfill-tenant-flags.ps1
+```
+

package/templates/commands/deploy-release.md

@@ -74,6 +74,37 @@ Include them anyway, or drop them from this deploy? (include / drop / cancel)
 
 Wait for the answer. `drop` removes them from **this deploy only** — they stay in the release.
 
+## Step 3b: Scripts That Have to Be Run
+
+A deployment script — a SQL migration, a data backfill, a PowerShell step — is attached to the work item it belongs to, and it has to run in **every** environment that item's code lands in. A promotion carries the code; it does not carry the script, and nothing in the PR says one exists. That is how an environment ends up half-deployed.
+
+Fetch each carried work item with its attachments — `wit_work_item` `action: get`, `expand: "Relations"`, one call per item (`get_batch` has no `expand`) — and keep every relation whose `rel` is `AttachedFile` and whose filename extension is **not** a document, image or video:
+
+```
+.xlsx .xls .xlsm .xlsb .csv  .docx .doc .docm  .pdf
+.png .jpg .jpeg .gif .bmp .ico .svg .webp .tiff .tif
+.mp4 .mov .avi .webm .mkv .wmv .flv .m4v
+```
+
+Everything else counts, extensionless files included. The rule is deliberately loose, because the two mistakes do not cost the same: a filename someone glances at and dismisses costs seconds, a migration nobody ran costs an environment.
+
+Show them with the gate check, before Step 4's confirmation:
+
+```
+📜 Scripts to run with this promotion:
+
+| Work Item | Script |
+|-----------|--------|
+| AB#1234 | 2026-09-11_add_delivery_index.sql |
+| AB#1240 | backfill-tenant-flags.ps1 |
+
+Download them from the work items. This command does not run them.
+```
+
+If nothing carries an attachment, say `No deployment scripts attached` on one line and move on.
+
+**Reported, never enforced.** A script does not block the promotion and does not change the gate check: the attachment may already have been run, may be a reference copy, may not be a script at all. Listing it is the whole job — the person deploying decides.
+
 ## Step 4: Confirm
 
 ```
@@ -147,7 +178,7 @@ Cherry-picking commits for Release #{N}:
    - **sourceRefName**: `refs/heads/release/{N}-to-<environment>`
    - **targetRefName**: `refs/heads/<target-environment-branch>`
    - **title**: `Release #{N} → {Environment}`
-   - **description**: List all work items included with their IDs and titles
+   - **description**: List all work items included with their IDs and titles, and — under a `Scripts to run` heading — any deployment scripts found in Step 3b, so whoever merges sees them without opening the work items
 3. Link all work items to the PR via `wit_link_work_item_to_pull_request`
 
 ## Step 8: Pick Who Verifies Each Group (before the merge)
@@ -217,9 +248,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
+
+Never trigger the CD pipeline by hand — it triggers on the merge.
 
-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:
+### 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 +274,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`.
 
@@ -294,6 +412,13 @@ Next: {the human step — "QA tests on Test and sets Ready for Staging" / "stake
 
 If the user said `stop watching`, or an update fails, leave the rest alone, say exactly which items were and were not updated, and note that `/track release {N}` will flag the lag later.
 
+If any carried item had a deployment script (Step 3b), repeat it here — this is the moment it has to run, and the list is stale in the scroll-back by now:
+
+```
+📜 Still to run on {environment}: AB#1234 2026-09-11_add_delivery_index.sql, AB#1240 backfill-tenant-flags.ps1
+```
+
+
 ## Step 11: Notify Team (if Teams MCP is configured)
 
 Send a notification to the project's Teams channel via the Microsoft Teams MCP server — once when the PR is created:

package/templates/commands/promote.md

@@ -79,6 +79,37 @@ Which? (1 / 2)
 
 For `main → dev` the gate is `Code Review`: an item still at `Code Review` whose commits are on `main` has had its PR merged, which is exactly right — not a warning. Features and Tasks are skipped. Items *ahead* of the gate are reported and left alone.
 
+## Step 3b: Scripts That Have to Be Run
+
+A deployment script — a SQL migration, a data backfill, a PowerShell step — is attached to the work item it belongs to, and it has to run in **every** environment that item's code lands in. A promotion carries the code; it does not carry the script, and nothing in the PR says one exists. That is how an environment ends up half-deployed.
+
+Fetch each carried work item with its attachments — `wit_work_item` `action: get`, `expand: "Relations"`, one call per item (`get_batch` has no `expand`) — and keep every relation whose `rel` is `AttachedFile` and whose filename extension is **not** a document, image or video:
+
+```
+.xlsx .xls .xlsm .xlsb .csv  .docx .doc .docm  .pdf
+.png .jpg .jpeg .gif .bmp .ico .svg .webp .tiff .tif
+.mp4 .mov .avi .webm .mkv .wmv .flv .m4v
+```
+
+Everything else counts, extensionless files included. The rule is deliberately loose, because the two mistakes do not cost the same: a filename someone glances at and dismisses costs seconds, a migration nobody ran costs an environment.
+
+Show them with the gate check, before the confirmation:
+
+```
+📜 Scripts to run with this promotion:
+
+| Work Item | Script |
+|-----------|--------|
+| AB#1234 | 2026-09-11_add_delivery_index.sql |
+| AB#1240 | backfill-tenant-flags.ps1 |
+
+Download them from the work items. This command does not run them.
+```
+
+If nothing carries an attachment, say `No deployment scripts attached` on one line and move on.
+
+**Reported, never enforced.** A script does not block the promotion and does not change the gate check: the attachment may already have been run, may be a reference copy, may not be a script at all. Listing it is the whole job — the person deploying decides.
+
 Then confirm: `Promote {count} commits from {source} to {target}? (yes/no)` — and wait.
 
 ## Step 4: Create PR
@@ -88,7 +119,7 @@ Create a PR directly from the source branch to the target branch via Azure DevOp
 - **sourceRefName**: `refs/heads/<source-branch>`
 - **targetRefName**: `refs/heads/<target-branch>`
 - **title**: `Promote {source} → {target}`
-- **description**: List all commits and associated work items being promoted
+- **description**: List all commits and associated work items being promoted, and — under a `Scripts to run` heading — any deployment scripts found in Step 3b, so whoever merges sees them without opening the work items
 
 Link the associated work items to the PR.
 
@@ -159,9 +190,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
+
+### 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.
 
-Do NOT merge the PR yourself — a reviewer approves and completes it. Report the PR, then watch for the deployment:
+Report the PR either way:
 
 ```
 Promotion PR created: {source} → {target}
@@ -169,13 +209,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`.
 
@@ -228,3 +343,10 @@ Next: {the human step — "QA tests on Test and sets Ready for Staging" / "stake
 ```
 
 If the user said `stop watching`, or an update fails, leave the rest alone, say exactly which items were and were not updated, and note that `/track` will flag the lag later.
+
+If any carried item had a deployment script (Step 3b), repeat it here — this is the moment it has to run, and the list is stale in the scroll-back by now:
+
+```
+📜 Still to run on {target}: AB#1234 2026-09-11_add_delivery_index.sql, AB#1240 backfill-tenant-flags.ps1
+```
+

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,9 +179,18 @@ 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.
 
+#### Deployment Scripts
+
+A SQL migration or a backfill script is attached to the work item it belongs to, and it has to run in **every** environment that item's code lands in — test, then staging, then prod. The promotion carries the code, never the script.
+
+`/promote`, `/cherry-pick` and `/deploy-release` therefore read the carried items' attachments (`wit_work_item` `action: get`, `expand: "Relations"`) and list any that look like something to run: an `AttachedFile` whose extension is **not** a document, image or video (`.docx .xlsx .csv .pdf .png .jpg .mp4` and friends). Everything else counts — the rule is loose on purpose, because a filename glanced at and dismissed costs seconds while a migration nobody ran costs an environment. The list appears before the confirmation, in the PR description, and again once the pipeline is green, which is when it actually has to be run.
+
+**Reported, never enforced.** A script never blocks a promotion and never changes the gate check — it may already have been run, or be a reference copy. The person deploying decides; the commands only make sure nobody finds out afterwards.
+
 #### Verifier Assignment
 
 Moving an item to `Testing`, `Staging`, or `Deployed` puts it on someone's plate, so `/promote`, `/cherry-pick`, and `/deploy-release` also change who owns it. The developer implemented it; from here on it belongs to whoever checks it in that environment.
@@ -207,7 +216,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 +236,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 +246,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 +311,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 → list deployment scripts → 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 → list deployment scripts → 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`) → list deployment scripts → 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 |