@chris1807/claude-kit 2.1.54 → 2.1.56

package/README.md

@@ -209,9 +209,9 @@ your-project/                      ← Project-specific
 │   │   ├── deploy.md              # /deploy "commit message"
 │   │   ├── create-release.md      # /create-release 23
 │   │   ├── deploy-release.md      # /deploy-release 23 staging
-│   │   ├── cherry-pick.md         # /cherry-pick AB#1234 production
-│   │   ├── promote.md             # /promote staging production
-│   │   ├── rollback.md            # /rollback AB#1234 production
+│   │   ├── cherry-pick.md         # /cherry-pick AB#1234 prod
+│   │   ├── promote.md             # /promote main dev
+│   │   ├── rollback.md            # /rollback AB#1234 prod
 │   │   ├── add-to-release.md      # /add-to-release 24 AB#4599
 │   │   ├── status.md              # /status release 24
 │   │   ├── cleanup-branches.md    # /cleanup-branches
@@ -305,7 +305,7 @@ Claude automatically:
 1. Runs pre-flight checks (dotnet build, tsc)
 2. Stages and commits with the provided message
 3. Pushes the current branch
-4. Triggers the CD pipeline if on an environment branch
+4. Triggers the CD pipeline if on an environment branch (`dev`, `test`, `staging`, `prod`) — never on `main`, which has no pipeline
 
 ### Create a Release
 
@@ -325,31 +325,37 @@ Claude automatically:
 ```
 
 Claude automatically:
-1. Finds all work items in Release #23
+1. Finds all work items in Release #23 and checks each against the environment's gate state (`Ready for Staging` here)
 2. Cherry-picks their commits into `release/23-to-staging`
-3. Creates a PR targeting the staging branch
+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
+
+The same command walks a release through `test` → `staging` → `prod`; with no environment given it picks the next one.
 
 ### Cherry-Pick Work Items
 
 ```
-/cherry-pick AB#1234 AB#1235 production
+/cherry-pick AB#1234 AB#1235 prod
 ```
 
-Cherry-picks specific work items to an environment without a formal release.
+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.
 
 ### Promote an Environment
 
 ```
-/promote staging production
+/promote main dev
+/promote staging prod
+/promote                  ← auto-detects from the current branch
 ```
 
-Creates a PR to promote all code from staging to production. Shows a summary of all included commits before confirming.
+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.
 
 ### Rollback a Deployment
 
 ```
-/rollback AB#1234 production
+/rollback AB#1234 prod
 /rollback last staging
 ```
 
@@ -411,15 +417,30 @@ Finds and deletes branches that have been fully merged. Protects environment bra
 
 ### Target State (All Projects)
 
-Every project should converge to this standard. Each long-lived branch maps to an Azure subscription and environment:
+`main` is the **compare branch** — the default branch, the one feature PRs target, and the one every environment is compared against. **Merging into `main` deploys nothing.** Each environment has its own branch, and a PR merging into that branch is what triggers its CD pipeline:
+
+| Branch | Environment | Deploys When |
+|--------|-------------|-------------|
+| `main` | — (compare / integration) | **Never** — a PR merging into `main` does not deploy |
+| `dev` | Development | PR merged into `dev` |
+| `test` | Test (QA) | PR merged into `test` |
+| `staging` | Staging | PR merged into `staging` |
+| `prod` | Production | PR merged into `prod` |
+
+> **Note:** A project that hasn't migrated yet (e.g. one that still has only `main` and `develop`) keeps working — every command reads the project's Pipeline Configuration table and uses the branch you're on. No branch names are hardcoded.
+
+### Work Item States Follow the Environments
+
+Every environment has a work item state, and the promotion commands keep them in sync. The "Ready for …" states are human sign-offs; the commands never set them.
 
-| Branch | Azure Subscription | Environment | Deploys When |
-|--------|-------------------|-------------|-------------|
-| `develop` | Dev | Development | PR merged into `develop` |
-| `staging` | Staging | Staging | PR merged into `staging` |
-| `main` | Production | Production | PR merged into `main` (with approval gate) |
+| Promotion | Gate (item should already be…) | State after the PR merges |
+|-----------|-------------------------------|---------------------------|
+| `main → dev` | `Code Review` | `Ready for Testing` |
+| `dev → test` | `Ready for Testing` | `Testing` |
+| `test → staging` | `Ready for Staging` (QA sign-off) | `Staging` |
+| `staging → prod` | `Ready to Deploy` (stakeholder sign-off) | `Deployed` |
 
-> **Note:** Some projects are not yet in sync — they may use `master` instead of `main`, or lack a `staging` branch. All commands work dynamically with whatever branch you're on. No branch names are hardcoded.
+`/deploy-release`, `/cherry-pick`, and `/promote` check the gate before creating the PR, ask who verifies each product group while the PR is in review, then watch the PR and the environment's CD pipeline — on a green pipeline they set the state and the assignee together. A failed pipeline changes nothing. `/status` flags anything whose state lags the branch it's on.
 
 ### Branch Naming
 
@@ -439,11 +460,12 @@ The branch is always created off the **current branch** — no assumptions are m
 
 ### Code Promotion Flow
 
-Code flows through environments via PRs, never by direct push:
+Code flows through environments via PRs, never by direct push. Every merge **after** `main` deploys:
 
 ```
-feature/AB#1234-... ──PR──▸ develop ──PR──▸ staging ──PR──▸ main
-   (work branch)            (Dev)          (Staging)      (Production)
+feature/AB#1234-... ──PR──▸ main ──PR──▸ dev ──PR──▸ test ──PR──▸ staging ──PR──▸ prod
+   (work branch)          (compare,     (Dev)       (Test)        (Staging)      (Production)
+                          no deploy)
 ```
 
 ---
@@ -462,8 +484,8 @@ claude
 ```
 
 ```
-# Switch to the develop branch first
-git checkout develop
+# Start from the compare branch
+git checkout main
 
 # Implement the work item
 /implement AB#1234
@@ -478,9 +500,15 @@ Claude will:
 6. Implement using backend and/or frontend agents
 7. Run all quality checks (build, lint, tests, review)
 8. Generate a UAT checklist and **pause for you to manually test**
-9. After you confirm "testing passed", create a PR targeting `develop`
+9. After you confirm "testing passed", create a PR targeting `main`, close the child Task with its hours, and move the work item to `Code Review`
 
-The PR merges into `develop`, which triggers the Dev environment CD pipeline.
+The PR merges into `main`. **That merge deploys nothing** — `main` is the compare branch. The work reaches Dev when `main` is promoted:
+
+```
+/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.
 
 ### Step 2: Deploy Changes (Quick Commits)
 
@@ -490,11 +518,11 @@ For smaller changes that don't need the full `/implement` workflow:
 /deploy "Fix typo in dashboard header"
 ```
 
-This commits, pushes, and triggers the pipeline if you're on an environment branch. If you're on a feature branch, it just pushes — the pipeline triggers on PR merge.
+This commits, pushes, and triggers the pipeline if you're on an environment branch (`dev`, `test`, `staging`, `prod`). On `main` or a feature branch it just pushes — nothing deploys until the work is promoted.
 
 ### Step 3: Group Work Items into a Release
 
-Once multiple work items are merged to `develop` and tested in Dev, group them into a release:
+Once multiple work items are merged to `main` and smoke-tested on Dev, group them into a release:
 
 ```
 /create-release 23
@@ -508,23 +536,25 @@ Claude will:
 2. Show you the list and ask for confirmation
 3. Create a `Release #23` iteration in Azure DevOps
 4. Assign all work items to the iteration and tag them with `release-23`
-5. Tell you how to deploy: `/deploy-release 23 staging` or `/deploy-release 23 production`
+5. Tell you how to deploy: `/deploy-release 23 test`, then `staging`, then `prod`
 
-### Step 4: Deploy a Release to Staging
+### Step 4: Deploy a Release to Test, then Staging
 
 ```
-/deploy-release 23 staging
+/deploy-release 23 test
 ```
 
 Claude will:
-1. Find all work items tagged `release-23`
-2. Find their associated commits on the `develop` branch
-3. Create a release branch: `release/23-to-staging`
+1. Find all work items tagged `release-23` and check each is at the gate for Test (`Ready for Testing`)
+2. Find their associated commits on `dev`
+3. Create a release branch: `release/23-to-test`
 4. Cherry-pick all commits for each work item
-5. Create a PR from `release/23-to-staging` → `staging`
+5. Create a PR from `release/23-to-test` → `test`
 6. Link all work items to the PR
+7. Ask who verifies each product group on Test
+8. Watch the PR and the Test pipeline; on a green pipeline, move the work items to `Testing` and assign them to the approved verifiers
 
-After the PR is reviewed and merged, the Staging CD pipeline triggers automatically.
+After the PR is reviewed and merged, the Test CD pipeline triggers automatically. QA tests there and sets each passing item to `Ready for Staging`; then `/deploy-release 23 staging` repeats the process (gate `Ready for Staging`, state after merge `Staging`).
 
 ### Step 5: Test on Staging
 
@@ -532,45 +562,46 @@ QA and stakeholders test on the Staging environment. If issues are found, fix th
 
 ### Step 6: Deploy a Release to Production
 
-When staging testing passes:
+When stakeholders have verified on Staging and set the items to `Ready to Deploy`:
 
 ```
-/deploy-release 23 production
+/deploy-release 23 prod
 ```
 
-Same process — cherry-picks the release's commits to a PR targeting the production branch. After merge, the Production CD pipeline triggers (with approval gate).
+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.
 
 ### Selective Deployment
 
-If staging has 5 user stories but only 3 are ready for production:
+If staging has 5 user stories but only 3 are `Ready to Deploy`:
 
 **Option A: Create a smaller release**
 ```
 /create-release 24
 ```
-Include only the 3 ready stories, then `/deploy-release 24 production`.
+Include only the 3 ready stories, then `/deploy-release 24 prod`.
 
 **Option B: Cherry-pick specific items**
 ```
-/cherry-pick AB#1234 AB#1235 AB#1236 production
+/cherry-pick AB#1234 AB#1235 AB#1236 prod
 ```
 This cherry-picks just those 3 work items without creating a formal release.
 
 ### Promoting Without a Release
 
-To promote **all** code from one environment to the next (no cherry-picking):
+To promote **all** code from one branch to the next (no cherry-picking):
 
 ```
-/promote staging production
+/promote main dev
+/promote staging prod
 ```
 
-This creates a PR from `staging` → production branch containing everything. Use this when all staging code is ready for production.
+This creates a PR from the source branch to the next one in the chain containing everything. `main → dev` is the everyday first hop; `staging → prod` is for when everything on staging is approved.
 
 You can also auto-detect the next environment:
 ```
 /promote
 ```
-If you're on the `staging` branch, it auto-detects `staging → production`.
+If you're on `main`, it auto-detects `main → dev`; on `staging`, `staging → prod`.
 
 ### Hot Fix Workflow
 
@@ -578,7 +609,7 @@ For critical production issues:
 
 1. Switch to the production branch:
    ```
-   git checkout main
+   git checkout prod
    ```
 2. Run `/implement` with the Hot Fix work item:
    ```
@@ -587,7 +618,8 @@ For critical production issues:
 3. Claude creates a `hotfix/AB#9999-fix-crash-on-submit` branch
 4. Automated checks still run (build, lint, tests, review)
 5. **Manual UAT is skipped** — you get an abbreviated confirmation instead
-6. PR targets the production branch directly with a `hotfix` label
+6. PR targets `prod` directly with a `hotfix` label — merging it deploys straight to production
+7. Then bring the fix back to `main` (a second PR from the same branch, or `/cherry-pick AB#9999 main`) so the next `main → dev` promotion doesn't overwrite it
 
 ### Rollback a Deployment
 
@@ -595,7 +627,7 @@ If a deployment causes issues:
 
 **Revert specific work items:**
 ```
-/rollback AB#1234 production
+/rollback AB#1234 prod
 ```
 
 **Revert the most recent deployment:**
@@ -605,12 +637,12 @@ If a deployment causes issues:
 
 Claude will:
 1. Find the commits to revert
-2. Create a revert branch (e.g., `revert/2026-03-21-on-production`)
+2. Create a revert branch (e.g., `revert/2026-09-06-on-prod`)
 3. Run `git revert` on each commit
 4. Run pre-flight checks on the reverted code
 5. Create a PR targeting the environment branch
 
-Merge the PR to deploy the rollback.
+Merge the PR to deploy the rollback. Work item states are left alone — Claude tells you which items were reverted so you can decide. If the reverted commits are also on `main`, the next promotion brings them back unless the revert is applied there too.
 
 ### Code Review
 
@@ -639,14 +671,14 @@ Claude reviews for:
 | `/deep-review` | `/deep-review 142` | Deep, Ultracode-orchestrated review: checks out the branch, builds/tests it, verifies every requirement, checks for regressions, flags out-of-scope changes, then comments + votes |
 | `/resolve-feedback` | `/resolve-feedback 142` | Address unresolved PR comment threads, push fixes, reply + resolve threads |
 | `/fix-review` | `/fix-review 142` | Fix everything flagged on a PR — human reviewer comments and automated `/review` findings alike: implement in severity order, validate, push, resolve threads |
-| `/deploy` | `/deploy "message"` | Commit, push, trigger pipeline if on environment branch |
+| `/deploy` | `/deploy "message"` | Commit, push, trigger pipeline if on an environment branch (`dev`/`test`/`staging`/`prod`) — never on `main` |
 | `/create-release` | `/create-release 23` | Group work items into Release #23 iteration with tags |
-| `/deploy-release` | `/deploy-release 23 staging` | Cherry-pick release work items to environment via PR |
+| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → cherry-pick release work items to environment via PR → ask who verifies → advance + assign on a green pipeline |
 | `/add-to-release` | `/add-to-release 24 AB#4599` | Add work items to an existing release |
-| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 production` | Cherry-pick specific work items to environment via PR |
-| `/promote` | `/promote staging production` | PR to promote all code between environments |
-| `/rollback` | `/rollback AB#1234 production` | Revert specific commits on an environment via PR |
-| `/status` | `/status release 24` | Check status of a release, pipeline, work item, or environment |
+| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → cherry-pick specific work items to environment via PR → ask who verifies → advance + assign on a green pipeline |
+| `/promote` | `/promote main dev` | PR to promote all code to the next branch in the chain (`main → dev → test → staging → prod`) → ask who verifies → advance + assign on a green pipeline |
+| `/rollback` | `/rollback AB#1234 prod` | Revert specific commits on an environment via PR |
+| `/status` | `/status release 24` | Check status of a release, pipeline, work item, or environment; flags work items whose state lags their environment |
 | `/plan-backlog` | `/plan-backlog [project]` | Sweep backlog for Dev Ready stories with points and no tasks → propose one child task with hours per story |
 | `/plan-sprint` | `/plan-sprint [project]` | Sweep the current sprint for stories/bugs with no child tasks → propose one child task with hours per item |
 | `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for unpointed items ready to estimate — stories in `Design Approved`, bugs in `New` (bugs have no design states) → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated). Also audits the drop-out queue — tagged bugs and stories bounced to Design Review — for items whose creator answered but which nobody returned to the sweep |
@@ -725,7 +757,7 @@ Claude maintains persistent memory across sessions in `~/.claude/projects/.../me
 | Memory Type | Purpose | Example |
 |-------------|---------|---------|
 | **user** | Who you are, preferences, expertise | "Senior .NET dev, prefers terse responses" |
-| **feedback** | What to do / avoid (self-improving) | "Always push to both main and develop" |
+| **feedback** | What to do / avoid (self-improving) | "Never enable 'Complete associated work items' when merging a PR" |
 | **project** | Decisions, priorities, blockers | "Using Stripe instead of Dwolla because..." |
 | **reference** | URLs, credentials, external resources | "Staging URL: https://..." |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.54",
+  "version": "2.1.56",
   "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/agents/project/deployer.md

@@ -23,8 +23,8 @@ You deploy code changes to Azure environments. Follow the standard sequence for
 
    | File family | Parallel files to check |
    |-------------|------------------------|
-   | `appsettings.json` | `appsettings.Development.json`, `appsettings.Staging.json`, `appsettings.QA.json`, `appsettings.Production.json` |
-   | `.env` | `.env.development`, `.env.staging`, `.env.qa`, `.env.production`, `.env.local`, `.env.example` |
+   | `appsettings.json` | `appsettings.Development.json`, `appsettings.Test.json`, `appsettings.QA.json`, `appsettings.Staging.json`, `appsettings.Production.json` |
+   | `.env` | `.env.development`, `.env.test`, `.env.qa`, `.env.staging`, `.env.production`, `.env.local`, `.env.example` |
 
    Present a (key × environment) table to the user. For any missing cell, prompt the user to supply a value (real, placeholder, or empty) before pushing, or to confirm the omission is intentional because the key is wired through a pipeline variable group, Key Vault, or App Configuration for that environment. Do NOT push until every missing entry is either filled in or explicitly skipped by the user.
 
@@ -47,10 +47,11 @@ Push only the current branch. Do NOT cross-push to other branches — deployment
 
 ### Step 4: Trigger Pipeline (Conditional)
 
-Only trigger the CD pipeline if you are pushing directly to an environment branch (the branch a CD pipeline watches). Check the project's CLAUDE.md or pipeline configuration for which branches map to which environments.
+Only trigger the CD pipeline if you are pushing directly to an environment branch (the branch a CD pipeline watches). Check the project's CLAUDE.md **Pipeline Configuration** table for which branches map to which environments. The standard layout is `main` (compare branch — **no pipeline, merging into it deploys nothing**) followed by the environment branches `dev → test → staging → prod`, each deploying when a PR merges into it.
 
-- **On an environment branch** (e.g., `develop`, `staging`, `main`): Trigger the appropriate CD pipeline using the Azure DevOps MCP server.
-- **On a feature/hotfix/bugfix/story/work branch**: Do NOT trigger the pipeline. It will trigger automatically when the PR is merged into the target branch.
+- **On an environment branch** (`dev`, `test`, `staging`, `prod` — a row with pipeline IDs): Trigger the listed CD pipeline(s) using the Azure DevOps MCP server.
+- **On `main`**: Do NOT trigger anything. Report that the change will deploy when `main` is promoted to `dev`.
+- **On a feature/hotfix/bugfix/story/work branch**: Do NOT trigger the pipeline. The work deploys when it is promoted after the PR merges into `main`.
 
 ### Step 5: Monitor
 
@@ -69,9 +70,10 @@ These operations are performed when the user explicitly requests promotions, che
 
 When asked to promote code from one environment to the next:
 
-1. Create a PR from the source branch to the target branch (e.g., `develop` → `staging`, or `staging` → `main`)
-2. Include a summary of all changes being promoted
+1. Create a PR from the source branch to the next branch in the chain (`main` → `dev`, `dev` → `test`, `test` → `staging`, `staging` → `prod`)
+2. Include a summary of all changes being promoted and the work items they carry
 3. After PR is merged, the CD pipeline for the target environment triggers automatically
+4. Once the user confirms the merge, advance the carried User Stories / Bugs / Hot Fixes to the environment's state (`dev` → `Ready for Testing`, `test` → `Testing`, `staging` → `Staging`, `prod` → `Deployed`) — never backward, never a Feature or Task. The `/promote` command documents the full gate-check and state rules
 
 ### Deploy Release
 
@@ -86,6 +88,7 @@ When asked to deploy a release (e.g., "deploy release #23 to staging"):
 7. Push the release branch and create a PR to the target environment branch
 8. Link all work items to the PR
 9. After merge, the CD pipeline triggers automatically
+10. Once the user confirms the merge, advance the carried work items to the environment's state (see Promote to Environment, item 4)
 
 ### Cherry-Pick Deployment (Ad-Hoc)
 
@@ -97,6 +100,7 @@ When asked to deploy specific stories/commits outside of a formal release:
 4. If conflicts arise, STOP and report them — do not resolve automatically
 5. Push the cherry-pick branch and create a PR to the target environment branch
 6. After merge, the CD pipeline triggers automatically
+7. Once the user confirms the merge, advance the carried work items to the environment's state (see Promote to Environment, item 4)
 
 ### Rollback
 
@@ -108,6 +112,8 @@ When asked to roll back a deployment:
 4. Run pre-flight checks (Step 1) on the reverted code
 5. Push and create a PR to the environment branch
 6. For production rollbacks, treat as urgent — flag to the user immediately
+7. Do not change work item states on a rollback — tell the user which items were reverted and let them decide
+8. If the reverted commits are also on `main`, warn that the next promotion brings them back unless the revert is applied to `main` too
 
 ---
 

package/templates/commands/cherry-pick.md

@@ -2,35 +2,47 @@ Cherry-pick specific work items to an environment. Usage: `/cherry-pick <work-it
 
 Parse `$ARGUMENTS` to extract:
 - **Work item IDs**: one or more IDs (e.g., "AB#1234 AB#1235" or "1234, 1235")
-- **Target environment**: the environment to deploy to (e.g., "staging", "production")
+- **Target environment**: the environment to deploy to (`dev`, `test`, `staging`, `prod`/`production`) or its branch. `main` is also a valid target — that is how a hot fix that went straight to `prod` gets brought back into the compare branch.
 
-## Step 1: Read the Work Items
+## Environment ↔ State Reference
 
-Fetch each work item from Azure DevOps via MCP. Present the list:
+Resolve branch names from the project's `CLAUDE.md` **Pipeline Configuration** table — never hardcode them. The first row is the compare branch (`main`; **merging into it deploys nothing**); the rows below are the environment branches in promotion order, and a PR merging into one of them triggers its pipeline:
+
+| Branch | Environment | Gate — items should already be in… | State set after the PR merges |
+|---|---|---|---|
+| `main` | — (compare branch) | — | *(no change)* |
+| `dev` | Dev | `Code Review` (merged to `main`) | `Ready for Testing` |
+| `test` | Test | `Ready for Testing` | `Testing` |
+| `staging` | Staging | `Ready for Staging` | `Staging` |
+| `prod` | Production | `Ready to Deploy` | `Deployed` |
+
+`Ready for Staging` and `Ready to Deploy` are set by QA and stakeholders — **never by this command**.
+
+## Step 1: Read the Work Items and Gate-Check Them
+
+Fetch each work item from Azure DevOps via MCP. Compare each one's `System.State` with the target's gate and annotate anything behind it (QA or a stakeholder hasn't signed off) or ahead of it (already been through this environment). Features and Tasks are listed but not gate-checked.
 
 ```
 ## Cherry-Pick to {environment}
 
-| ID | Type | Title | State |
-|----|------|-------|-------|
-| AB#1234 | User Story | Add payment export | Ready for Testing |
-| AB#1235 | Bug | Fix login redirect | Ready for Testing |
+| ID | Type | Title | State | Gate ({gate state}) |
+|----|------|-------|-------|---------------------|
+| AB#1234 | User Story | Add payment export | Ready to Deploy | ✓ |
+| AB#1235 | Bug | Fix login redirect | Staging | ⚠ behind — stakeholders haven't set Ready to Deploy |
 
-Cherry-pick {count} work items to {environment}? (yes/no)
+Cherry-pick {count} work items to {environment}? Items behind the gate: include / drop / cancel
 ```
 
-Wait for confirmation.
+Wait for confirmation. `drop` removes flagged items from this cherry-pick only.
 
 ## Step 2: Find Commits
 
-For each work item, find associated commits using `repo_search_commits` with `includeWorkItems: true`, or by searching for `AB#{id}` in commit messages on the source branch.
+For each work item, find associated commits using `repo_search_commits` with `includeWorkItems: true`, or by searching for `AB#{id}` in commit messages on the source branch (the environment one step before the target — e.g. `staging` when targeting `prod`, `main` when targeting `dev`).
 
 If no commits are found for a work item, STOP and report which work item has no associated commits.
 
 ## Step 3: Create Cherry-Pick Branch
 
-Determine the target environment branch. Do NOT hardcode branch names — check the project's CLAUDE.md or pipeline configuration.
-
 ```bash
 git checkout <target-environment-branch>
 git pull origin <target-environment-branch>
@@ -61,7 +73,7 @@ Options:
 Which option? (1 / 2 / 3)
 ```
 
-- **Option 1:** Run `git cherry-pick --skip` and continue with remaining work items. Note the skipped item in the summary.
+- **Option 1:** Run `git cherry-pick --skip` and continue with remaining work items. Note the skipped item in the summary — it does **not** get its state advanced or its assignee changed in Step 8.
 - **Option 2:** Run `git cherry-pick --abort`, delete the cherry-pick branch, and switch back to the original branch.
 - **Option 3:** Wait for the user to resolve conflicts and run `git cherry-pick --continue`, then proceed.
 
@@ -82,15 +94,143 @@ Cherry-picking:
    - **description**: List all work items with IDs and titles
 3. Link all work items to the PR via `wit_link_work_item_to_pull_request`
 
-## Step 6: Present Summary
+## Step 6: Pick Who Verifies Each Group (before the merge)
+
+When the target is `main` there is no pipeline, no state change, and **no assignment** — say so and skip to Step 8's summary.
+
+Otherwise the items are 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 8 together with the state change, once the pipeline is green.
+
+### 6a. 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 cherry-picked **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 4) or dropped at the gate (Step 1) are not on the branch — leave them out. Features and Tasks are never assigned by this command.
+
+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.
+
+### 6b. 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 cherry-picked 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.
+
+### 6c. Ask
+
+```
+## Who verifies 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 every group to the same person.
+```
+
+### 6d. 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 | Deployed |
+| AB#1240 | PAY - Fix login redirect | PAY | Pat Ruiz | Deployed |
+
+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
+
+Do NOT merge the PR yourself — a reviewer approves and completes it. Report the PR, then watch for the deployment:
 
 ```
 Cherry-pick PR created for {environment}.
 
 PR: {pr-url}
 Work items:
-- AB#1234: Add payment export
-- AB#1235: Fix login redirect
+- AB#1234: COM - Add payment export
+- AB#1240: PAY - Fix login redirect
 
-Merge the PR to trigger the CD pipeline for {environment}.
+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.
 ```
+
+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:
+
+```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
+```
+
+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 8: Assign and Advance States (automatic, on a green pipeline)
+
+This step runs **by itself** the moment the pipeline reports success — do not ask again; the approval in Step 6d covers it. All three preconditions must hold: the PR is `completed`, **every** CD run for {environment} is `succeeded`, and a Step 6d 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 6d approval yet (user hasn't answered) → do the state changes only when they answer; don't guess an assignee.
+
+For every cherry-picked 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.
+   - Skipped (conflict) or dropped items 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. Don't silently swallow it.
+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:
+
+```
+Cherry-pick is deployed to {environment} (pipeline {build-number}, succeeded).
+
+| ID | State: was → now | Assignee: was → now |
+|----|------------------|---------------------|
+| AB#1234 | Ready to Deploy → Deployed | Chris Waters → Jane Doe |
+| AB#1240 | Ready to Deploy → Deployed | 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 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.