@chris1807/claude-kit 2.1.55 → 2.1.57

package/templates/commands/deploy-release.md

@@ -83,7 +83,8 @@ This will:
 1. Create a release branch: release/{N}-to-{environment}
 2. Cherry-pick all commits for the {count} work items
 3. Create a PR targeting `{target-branch}` — merging it triggers the {environment} pipeline
-4. After you confirm the merge, move the work items to `{state after merge}`
+4. Ask who verifies each product group on {environment} (before the merge)
+5. Watch the pipeline — once it's green, set the work items to `{state after merge}` and assign them to the approved verifiers
 
 Proceed? (yes/no)
 ```
@@ -126,7 +127,7 @@ Options:
 Which option? (1 / 2 / 3)
 ```
 
-- **Option 1:** Run `git cherry-pick --skip` and continue. Note the skipped item in the summary — it does **not** get its state advanced in Step 9.
+- **Option 1:** Run `git cherry-pick --skip` and continue. Note the skipped item in the summary — it does **not** get its state advanced or its assignee changed in Step 10.
 - **Option 2:** Run `git cherry-pick --abort`, delete the release branch, switch back. Report which items were NOT deployed.
 - **Option 3:** Wait for the user to resolve and run `git cherry-pick --continue`, then proceed.
 
@@ -149,7 +150,76 @@ Cherry-picking commits for Release #{N}:
    - **description**: List all work items included with their IDs and titles
 3. Link all work items to the PR via `wit_link_work_item_to_pull_request`
 
-## Step 8: Present Summary and Wait for the Merge
+## Step 8: Pick Who Verifies Each Group (before the merge)
+
+The release is about to land in {environment} for **someone** to verify. Decide who now, while the PR is still in review — nothing is written yet; the assignment is applied in Step 10 together with the state change, once the pipeline is green.
+
+### 8a. Group by title prefix
+
+Work item titles in the CSI Development project are `PREFIX - Title` (`COM`, `PAY`, `CDA`, `AUD`, `SER`, `PSSF`, `TPS`, `ILP`, `RBWO`, `MTG`, `CSI`). Group the deployed **User Stories, Bugs, and Hot Fixes** by that prefix. Titles with a missing or unrecognized prefix go in a `(no prefix)` group. Items skipped on a conflict (Step 6) or dropped at the gate (Step 3) are not on the branch — leave them out. Features and Tasks are never assigned by this command.
+
+A release that spans products lands in several groups — one question each. Different products usually have different verifiers, but the same person may take several groups; that is the normal case, not an error.
+
+### 8b. Build each group's candidate list from the items themselves
+
+For every item in the group, collect the distinct identities already on it:
+
+- **whoever set the gate state** — `wit_work_item` `action: list_revisions`, then the `System.ChangedBy` on the revision where `System.State` became the target's gate state (`Ready for Staging`, `Ready to Deploy`, …). That is the QA person or stakeholder who signed the item off, and it is usually the right verifier.
+- `System.CreatedBy` — who asked for the work
+- comment authors — `wit_work_item` `action: list_comments`
+- `System.ChangedBy` — the most recent editor
+
+Then **drop the developers**, so what remains is the non-developer names on the item:
+
+- each item's current `System.AssignedTo` (the dev who implemented it)
+- the PR author
+- the authors of the release commits — `git log --format='%an <%ae>' <target-branch>..HEAD | sort -u`
+
+Rank the survivors by how many items in the group they appear on — the gate-state signer first, then creators. **Do not invent names**, do not pull from the org directory or a team list, and do not carry a name over from another group's items — every candidate must come from the items in that group.
+
+If the developer filter empties a group's list, say so and show the unfiltered names marked `(also a developer here)`, plus the option to type a name.
+
+### 8c. Ask
+
+```
+## Who verifies Release #{N} on {environment}?
+
+**COM** — 2 items (AB#1234, AB#1236)
+  1. Jane Doe (jane@caresolutions.com) — set Ready to Deploy on both
+  2. Sam Lee (sam@caresolutions.com) — commented on AB#1234
+  3. Someone else — give me a name or email
+  4. Leave the current assignee alone
+
+**PAY** — 2 items (AB#1240, AB#1241)
+  1. Pat Ruiz (pat@caresolutions.com) — created both
+  2. Jane Doe (jane@caresolutions.com) — commented on AB#1240
+  3. Someone else
+  4. Leave the current assignee alone
+
+Reply per group — `COM 1, PAY 1` — or `all 1` to give the whole release to one person.
+```
+
+### 8d. Confirm the mapping
+
+Echo the resolved plan and wait for an explicit `yes`:
+
+```
+When the {environment} pipeline goes green I will apply:
+
+| ID | Title | Prefix | Assign to | State |
+|----|-------|--------|-----------|-------|
+| AB#1234 | COM - Add payment export | COM | Jane Doe | Staging |
+| AB#1236 | COM - View history | COM | Jane Doe | Staging |
+| AB#1240 | PAY - Fix login redirect | PAY | Pat Ruiz | Staging |
+
+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
+
+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:
 
 ```
 Release #{N} PR created for {environment}.
@@ -158,53 +228,90 @@ PR: {pr-url}
 Branch: release/{N}-to-{environment} → {target-branch}
 
 Work items included:
-- AB#1234: Add payment export
-- AB#1235: Fix login redirect
-- AB#1236: View history
+- AB#1234: COM - Add payment export
+- 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
+{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.
+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`.
+
+**How to wait.** Never block on a foreground `sleep`. If the Azure CLI with the `azure-devops` extension is available, arm a background watch that notifies you on a terminal state:
 
-Next steps:
-- Review and approve the PR
-- Merging it triggers the CD pipeline for {environment}
-- Reply `merged` once the PR is complete and the pipeline is green — I'll move these {count} work items to `{state after merge}`. (Or `skip` to leave the states alone.)
+```bash
+# <run-id> is the run identified in step 2 — never "the latest run on the branch",
+# which can be a run queued before the merge and already completed.
+until az pipelines runs show --org <org-url> --project <project> \
+        --id <run-id> --query status -o tsv | grep -qx completed; do
+  sleep 60
+done
+az pipelines runs show --org <org-url> --project <project> \
+  --id <run-id> --query "[buildNumber,status,result]" -o tsv
 ```
 
-Do NOT trigger the CD pipeline — it triggers automatically on PR merge. Do NOT merge the PR yourself.
+Run it with `Monitor` (or Bash `run_in_background`) so the session stays usable. Watch the **run id**, and print `result` when it exits — a guard that only greps for success is silent through a failed or canceled deploy, which looks identical to one still running. One watch per pipeline when the branch has more than one.
+
+Without the CLI, re-poll through the Azure DevOps MCP on roughly a 60-second cadence and report progress as you go. If the deploy outlasts the session's attention, say where it stands and that `check` will re-poll immediately — never claim a pipeline succeeded that you have not seen succeed.
+
+## Step 10: Assign and Advance States (automatic, on a green pipeline)
 
-## Step 9: Advance Work Item States (after `merged`)
+This step runs **by itself** the moment the pipeline reports success — do not ask again; the approval in Step 8d covers it. All three preconditions must hold: the PR is `completed`, **every** CD run for {environment} is `succeeded`, and a Step 8d mapping was approved.
 
-When the user replies `merged`:
+- `partiallySucceeded` → not green. Report which stage failed and ask `proceed` / `hold`.
+- `failed` / `canceled` → change nothing. Report the run, the failing stage, and the log link (`pipelines_build_log`), and offer `/rollback` if the environment is broken.
+- No Step 8d approval yet (user hasn't answered) → do the state changes only when they answer; don't guess an assignee.
 
-1. **Confirm the PR is actually completed** via the Azure DevOps MCP (`status: completed`). If it isn't, say so and wait — never advance states for an unmerged PR.
-2. For every carried work item of type **User Story**, **Bug**, or **Hot Fix**, set `System.State` to the target environment's state (`Ready for Testing` / `Testing` / `Staging` / `Deployed`) via `wit_update_work_item` (or the batch variant).
+For every carried work item of type **User Story**, **Bug**, or **Hot Fix**, one `wit_work_item_write` update per item (or the batch variant) setting both fields:
+
+1. `System.State` → the target environment's state (`Ready for Testing` / `Testing` / `Staging` / `Deployed`).
    - **Never move backward.** An item already past the target state (e.g. `Deployed` when deploying to `staging`) keeps its state; note it.
-   - **Never touch a Feature or Task.** Features advance as their stories do; Tasks were closed at PR creation.
    - Items skipped in Step 6 (conflict) or dropped in Step 3 are not on the branch — leave them alone.
    - An invalid-state error means this project's template differs — confirm with `get_type`, report the item, continue with the rest. Don't silently swallow it.
-3. Report:
+2. `System.AssignedTo` → the person approved for that item's prefix group. Pass the identity's `uniqueName` / email, not the display name; if the update rejects it, resolve with `core_get_identity_ids` and retry once. A `Leave the current assignee alone` group keeps its assignee — never clear a field the user didn't ask you to clear.
+
+**Never touch a Feature or Task** — neither state nor assignee. Features advance as their stories do; Tasks were closed at PR creation.
+
+Report both fields, so a wrong assignment is easy to put back:
 
 ```
-Release #{N} is on {environment}.
+Release #{N} is on {environment} (pipeline {build-number}, succeeded).
 
-| ID | Was | Now |
-|----|-----|-----|
-| AB#1234 | Ready for Staging | Staging |
-| AB#1235 | Ready for Staging | Staging |
-| AB#1240 | Deployed | Deployed (unchanged — already ahead) |
+| ID | State: was → now | Assignee: was → now |
+|----|------------------|---------------------|
+| AB#1234 | Ready for Staging → Staging | Chris Waters → Jane Doe |
+| AB#1236 | Ready for Staging → Staging | Chris Waters → Jane Doe |
+| AB#1240 | Ready for Staging → Staging | Chris Waters → Pat Ruiz |
+| AB#1250 | Deployed (unchanged — already ahead) | unchanged |
 
 Next: {the human step — "QA tests on Test and sets Ready for Staging" / "stakeholders verify on Staging and set Ready to Deploy" / "verify in production, then Close"}.
 ```
 
-If the user replies `skip`, leave the states alone and note that `/status release {N}` will flag the lag later.
+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 `/status release {N}` will flag the lag later.
 
-## Step 10: Notify Team (if Teams MCP is configured)
+## Step 11: Notify Team (if Teams MCP is configured)
 
-Send a notification to the project's Teams channel via the Microsoft Teams MCP server:
+Send a notification to the project's Teams channel via the Microsoft Teams MCP server — once when the PR is created:
 
 ```
 🚀 Release #{N} PR created for {environment}
 PR: {pr-url}
-Work items: AB#1234, AB#1235, AB#1236
+Work items: AB#1234, AB#1236, AB#1240
 Awaiting review and merge.
 ```
 
+…and once when Step 10 completes, so the verifiers know it's their turn:
+
+```
+✅ Release #{N} deployed to {environment}
+COM (AB#1234, AB#1236) → Jane Doe
+PAY (AB#1240) → Pat Ruiz
+Items are now `{state}` — please verify.
+```
+
 If the Teams MCP server is not configured, skip this step silently.

package/templates/commands/promote.md

@@ -92,7 +92,76 @@ Create a PR directly from the source branch to the target branch via Azure DevOp
 
 Link the associated work items to the PR.
 
-## Step 5: Present Summary and Wait for the Merge
+## Step 5: Pick Who Verifies Each Group (before the merge)
+
+The items are about to land in {target environment} for **someone** to verify. Decide who now, while the PR is still in review — nothing is written yet; the assignment is applied in Step 7 together with the state change, once the pipeline is green.
+
+### 5a. Group by title prefix
+
+Work item titles in the CSI Development project are `PREFIX - Title` (`COM`, `PAY`, `CDA`, `AUD`, `SER`, `PSSF`, `TPS`, `ILP`, `RBWO`, `MTG`, `CSI`). Group the carried **User Stories, Bugs, and Hot Fixes** by that prefix. Titles with a missing or unrecognized prefix go in a `(no prefix)` group. Features and Tasks are never assigned by this command — leave them out of the grouping.
+
+One question per group. Different products usually have different verifiers, but the same person may take several groups — that is the normal case, not an error.
+
+### 5b. Build each group's candidate list from the items themselves
+
+For every item in the group, collect the distinct identities already on it:
+
+- **whoever set the gate state** — `wit_work_item` `action: list_revisions`, then the `System.ChangedBy` on the revision where `System.State` became the target's gate state (`Ready for Staging`, `Ready to Deploy`, …). That is the QA person or stakeholder who signed the item off, and it is usually the right verifier.
+- `System.CreatedBy` — who asked for the work
+- comment authors — `wit_work_item` `action: list_comments`
+- `System.ChangedBy` — the most recent editor
+
+Then **drop the developers**, so what remains is the non-developer names on the item:
+
+- each item's current `System.AssignedTo` (the dev who implemented it)
+- the PR author
+- the authors of the promoted commits — `git log origin/<target>..origin/<source> --format='%an <%ae>' | sort -u`
+
+Rank the survivors by how many items in the group they appear on — the gate-state signer first, then creators. **Do not invent names**, do not pull from the org directory or a team list, and do not carry a name over from another group's items — every candidate must come from the items in that group.
+
+If the developer filter empties a group's list, say so and show the unfiltered names marked `(also a developer here)`, plus the option to type a name.
+
+### 5c. Ask
+
+```
+## Who verifies on {environment}?
+
+**COM** — 2 items (AB#1234, AB#1236)
+  1. Jane Doe (jane@caresolutions.com) — created both
+  2. Sam Lee (sam@caresolutions.com) — commented on AB#1234
+  3. Someone else — give me a name or email
+  4. Leave the current assignee alone
+
+**PAY** — 2 items (AB#1240, AB#1241)
+  1. Jane Doe (jane@caresolutions.com) — created AB#1240
+  2. Pat Ruiz (pat@caresolutions.com) — commented on both
+  3. Someone else
+  4. Leave the current assignee alone
+
+Reply per group — `COM 1, PAY 2` — or `all 1` to give every group to the same person.
+```
+
+### 5d. Confirm the mapping
+
+Echo the resolved plan and wait for an explicit `yes`:
+
+```
+When the {environment} pipeline goes green I will apply:
+
+| ID | Title | Prefix | Assign to | State |
+|----|-------|--------|-----------|-------|
+| AB#1234 | COM - Add payment export | COM | Jane Doe | Staging |
+| AB#1236 | COM - View history | COM | Jane Doe | Staging |
+| AB#1240 | PAY - Fix login redirect | PAY | Pat Ruiz | Staging |
+
+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
+
+Do NOT merge the PR yourself — a reviewer approves and completes it. Report the PR, then watch for the deployment:
 
 ```
 Promotion PR created: {source} → {target}
@@ -100,22 +169,62 @@ Promotion PR created: {source} → {target}
 PR: {pr-url}
 
 {count} commits, {n} work items included.
-Merging the PR triggers the CD pipeline for {target}.
+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.
+```
+
+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.
+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`.
 
-Reply `merged` once the PR is complete and the pipeline is green — I'll move the {n} work items to `{state after merge}`. (Or `skip` to leave the states alone.)
+**How to wait.** Never block on a foreground `sleep`. If the Azure CLI with the `azure-devops` extension is available, arm a background watch that notifies you on a terminal state:
+
+```bash
+# <run-id> is the run identified in step 2 — never "the latest run on the branch",
+# which can be a run queued before the merge and already completed.
+until az pipelines runs show --org <org-url> --project <project> \
+        --id <run-id> --query status -o tsv | grep -qx completed; do
+  sleep 60
+done
+az pipelines runs show --org <org-url> --project <project> \
+  --id <run-id> --query "[buildNumber,status,result]" -o tsv
 ```
 
-Do NOT merge the PR automatically — the user or a reviewer must approve and merge.
+Run it with `Monitor` (or Bash `run_in_background`) so the session stays usable. Watch the **run id**, and print `result` when it exits — a guard that only greps for success is silent through a failed or canceled deploy, which looks identical to one still running. One watch per pipeline when the branch has more than one.
 
-## Step 6: Advance Work Item States (after `merged`)
+Without the CLI, re-poll through the Azure DevOps MCP on roughly a 60-second cadence and report progress as you go. If the deploy outlasts the session's attention, say where it stands and that `check` will re-poll immediately — never claim a pipeline succeeded that you have not seen succeed.
 
-When the user replies `merged`:
+## Step 7: Assign and Advance States (automatic, on a green pipeline)
 
-1. **Confirm the PR is actually completed** via the Azure DevOps MCP. If it isn't, say so and wait — never advance states for an unmerged PR.
-2. For every carried work item of type **User Story**, **Bug**, or **Hot Fix**, set `System.State` to the target's state (`Ready for Testing` / `Testing` / `Staging` / `Deployed`) via `wit_update_work_item`.
+This step runs **by itself** the moment the pipeline reports success — do not ask again; the approval in Step 5d covers it. All three preconditions must hold: the PR is `completed`, **every** CD run for {target} is `succeeded`, and a Step 5d mapping was approved.
+
+- `partiallySucceeded` → not green. Report which stage failed and ask `proceed` / `hold`.
+- `failed` / `canceled` → change nothing. Report the run, the failing stage, and the log link (`pipelines_build_log`), and offer `/rollback` if the environment is broken.
+- No Step 5d approval yet (user hasn't answered) → do the state changes only when they answer; don't guess an assignee.
+
+For every carried work item of type **User Story**, **Bug**, or **Hot Fix**, one `wit_work_item_write` update per item setting both fields:
+
+1. `System.State` → the target's state (`Ready for Testing` / `Testing` / `Staging` / `Deployed`).
    - **Never move backward** — an item already past the target state keeps it; note it.
-   - **Never touch a Feature or Task.**
    - An invalid-state error means this project's template differs — confirm with `get_type`, report the item, continue with the rest. Don't silently swallow it.
-3. Report a `Was → Now` table per item and the next human step (QA sets `Ready for Staging`; stakeholders set `Ready to Deploy`; verify in production, then `Closed`).
+2. `System.AssignedTo` → the person approved for that item's prefix group. Pass the identity's `uniqueName` / email, not the display name; if the update rejects it, resolve with `core_get_identity_ids` and retry once. A `Leave the current assignee alone` group keeps its assignee — never clear a field the user didn't ask you to clear.
+
+**Never touch a Feature or Task** — neither state nor assignee.
+
+Report both fields, so a wrong assignment is easy to put back:
+
+```
+{source} → {target} is deployed (pipeline {build-number}, succeeded).
+
+| ID | State: was → now | Assignee: was → now |
+|----|------------------|---------------------|
+| AB#1234 | Ready for Staging → Staging | Chris Waters → Jane Doe |
+| AB#1240 | Ready for Staging → Staging | Chris Waters → Pat Ruiz |
+| AB#1250 | Deployed (unchanged — already ahead) | unchanged |
+
+Next: {the human step — "QA tests on Test and sets Ready for Staging" / "stakeholders verify on Staging and set Ready to Deploy" / "verify in production, then Close"}.
+```
 
-If the user replies `skip`, leave the states alone and note that `/status` will flag the lag later.
+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 `/status` will flag the lag later.