@chris1807/claude-kit 2.1.54 → 2.1.55

package/templates/commands/deploy-release.md

@@ -2,7 +2,21 @@ Deploy release to the next environment. Usage: `/deploy-release <release-number>
 
 Parse `$ARGUMENTS` to extract:
 - **Release number**: required (e.g., "23" or "#23")
-- **Target environment**: optional — if not provided, auto-detect the next environment in the promotion flow
+- **Target environment**: optional — an environment name (`dev`, `test`, `staging`, `prod`/`production`) or its branch. If not provided, auto-detect the next environment in the promotion flow.
+
+## Environment ↔ State Reference
+
+Resolve branch names from the project's `CLAUDE.md` **Pipeline Configuration** table — never hardcode them. The first row is the compare branch (`main`; feature PRs target it, **merging into it deploys nothing**); the rows below are the environment branches in promotion order, and a PR merging into one of them is what triggers its pipeline. The standard layout, with the work item state that goes with each environment:
+
+| Branch | Environment | Gate — items should already be in… | State set after the PR merges |
+|---|---|---|---|
+| `main` | — (compare branch) | — | — |
+| `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**. If the project's table has different environments, confirm the type's states with `mcp__azure-devops__wit_work_item` (`action: get_type`) and map them the same way: a "Ready for X" gate → an "in X" state.
 
 ## Step 1: Read the Release
 
@@ -15,8 +29,8 @@ Present the release contents:
 
 | ID | Type | Title | State | Branch |
 |----|------|-------|-------|--------|
-| AB#1234 | User Story | Add payment export | Ready for Testing | story/AB#1234-add-payment-export |
-| AB#1235 | Bug | Fix login redirect | Ready for Testing | bugfix/AB#1235-fix-login-redirect |
+| AB#1234 | User Story | Add payment export | Ready for Staging | story/AB#1234-add-payment-export |
+| AB#1235 | Bug | Fix login redirect | Ready for Staging | bugfix/AB#1235-fix-login-redirect |
 
 {count} work items in this release.
 ```
@@ -25,18 +39,42 @@ If no work items are found, STOP and report the error.
 
 ## Step 2: Determine Target Environment
 
-If the user specified an environment, use it. Otherwise, auto-detect by checking which environment the work items are currently in:
+If the user specified an environment, use it. Otherwise auto-detect: find the **furthest** branch in the Pipeline Configuration table that already contains the work items' commits (`repo_search_commits` with `includeWorkItems: true`, or `git merge-base --is-ancestor <commit> origin/<branch>`), and target the **next row down**:
 
-| Current State | Next Environment |
+| Work items' commits are on… | Next target |
 |---|---|
-| Work items merged to `develop` | Deploy to **staging** |
-| Work items merged to `staging` | Deploy to **production** |
+| `main` only | `dev` |
+| `dev` | `test` |
+| `test` | `staging` |
+| `staging` | `prod` |
+| `prod` | Nothing — report that the release is fully deployed and stop |
+
+**Validation:** Verify all work items in the release have commits on the same source branch. If they are inconsistent (e.g., AB#1234 is on `test` but AB#1235 has nothing past `main`), present a warning listing which work items are on which branches and ask the user to confirm the target environment explicitly.
+
+## Step 3: Gate Check
 
-Check which environment branches contain the commits for these work items using `repo_search_commits` with `includeWorkItems: true`.
+Compare each work item's `System.State` with the gate for the target environment. Sort into three buckets:
 
-**Validation:** Verify all work items in the release have commits on the same source branch. If they are inconsistent (e.g., AB#1234 is on `develop` but AB#1235 has no commits), present a warning listing which work items are on which branches and ask the user to confirm the target environment explicitly.
+- **At the gate** — proceed silently.
+- **Behind the gate** (e.g. still `Testing` when the target is `staging`, or `Active` when the target is `test`) — QA or a stakeholder hasn't signed off yet.
+- **Ahead of the gate** (e.g. already `Deployed`, or `Staging` when the target is `test`) — it has already been through this environment; a redeploy is usually harmless but worth knowing.
 
-Confirm with the user:
+Features and Tasks aren't carried by state — list them and skip the check. If anything is behind or ahead, show it before asking to proceed:
+
+```
+⚠ Gate check for {environment} (expects `{gate state}`):
+
+| ID | State | Note |
+|----|-------|------|
+| AB#1236 | Testing | behind — QA hasn't marked it Ready for Staging |
+| AB#1240 | Deployed | ahead — already in production |
+
+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 4: Confirm
 
 ```
 Deploy Release #{N} ({count} work items) to {environment}?
@@ -44,16 +82,15 @@ Deploy Release #{N} ({count} work items) to {environment}?
 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 the {environment} branch
+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}`
 
 Proceed? (yes/no)
 ```
 
 Wait for confirmation.
 
-## Step 3: Create Release Branch
-
-Determine the target environment branch. Do NOT hardcode branch names — check the project's CLAUDE.md or use the branch-to-environment mapping:
+## Step 5: Create Release Branch
 
 ```bash
 # Switch to the target environment branch and pull latest
@@ -64,7 +101,7 @@ git pull origin <target-environment-branch>
 git checkout -b release/{N}-to-<environment>
 ```
 
-## Step 4: Cherry-Pick Work Item Commits
+## Step 6: Cherry-Pick Work Item Commits
 
 For each work item in the release:
 
@@ -89,7 +126,7 @@ Options:
 Which option? (1 / 2 / 3)
 ```
 
-- **Option 1:** Run `git cherry-pick --skip` and continue. Note the skipped item in the summary.
+- **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 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.
 
@@ -102,7 +139,7 @@ Cherry-picking commits for Release #{N}:
 [ ] AB#1236: View history (2 commits) — CONFLICT
 ```
 
-## Step 5: Push and Create PR
+## Step 7: Push and Create PR
 
 1. Push the release branch: `git push -u origin HEAD`
 2. Create a PR via Azure DevOps MCP:
@@ -112,7 +149,7 @@ 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 6: Present Summary
+## Step 8: Present Summary and Wait for the Merge
 
 ```
 Release #{N} PR created for {environment}.
@@ -127,13 +164,39 @@ Work items included:
 
 Next steps:
 - Review and approve the PR
-- Merge triggers the CD pipeline for {environment}
-- Update work item states in Azure DevOps after merge
+- 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.)
+```
+
+Do NOT trigger the CD pipeline — it triggers automatically on PR merge. Do NOT merge the PR yourself.
+
+## Step 9: Advance Work Item States (after `merged`)
+
+When the user replies `merged`:
+
+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).
+   - **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:
+
+```
+Release #{N} is on {environment}.
+
+| ID | Was | Now |
+|----|-----|-----|
+| AB#1234 | Ready for Staging | Staging |
+| AB#1235 | Ready for Staging | Staging |
+| AB#1240 | Deployed | Deployed (unchanged — already ahead) |
+
+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"}.
 ```
 
-Do NOT trigger the CD pipeline — it triggers automatically on PR merge.
+If the user replies `skip`, leave the states alone and note that `/status release {N}` will flag the lag later.
 
-## Step 7: Notify Team (if Teams MCP is configured)
+## Step 10: Notify Team (if Teams MCP is configured)
 
 Send a notification to the project's Teams channel via the Microsoft Teams MCP server:
 

package/templates/commands/deploy.md

@@ -11,16 +11,16 @@ Commit, push, and deploy the current changes. Usage: `/deploy [message]`
 
    | 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 table of new/changed keys and which environment files contain them. If any are missing, STOP and prompt:
 
    ```
    ⚠ The following keys are missing from one or more environment files:
 
-   | Key | Dev | Staging | QA | Prod |
-   |-----|-----|---------|----|----- |
+   | Key | Dev | Test | Staging | Prod |
+   |-----|-----|------|---------|------|
    | Foo:Bar | ✅ | ❌ | ❌ | ❌ |
 
    Add values (real, placeholder, or empty) for the missing environments before pushing?
@@ -70,10 +70,11 @@ Push only the current branch. Do NOT cross-push to other branches.
 
 ## Step 5: Pipeline (Conditional)
 
-Check if the current branch is an environment branch (a branch that a CD pipeline watches):
+Look the current branch up in the project's `CLAUDE.md` **Pipeline Configuration** table:
 
-- **On an environment branch**: Trigger the appropriate CD pipeline via Azure DevOps MCP. Monitor the build and report status.
-- **On a feature/work branch**: Do NOT trigger. Report that the pipeline will trigger on PR merge.
+- **On an environment branch** (`dev`, `test`, `staging`, `prod` — a row with pipeline IDs): Trigger the listed CD pipeline(s) via Azure DevOps MCP. Monitor the build and report status.
+- **On `main`** (the compare branch — its pipeline cell is `—`): Do NOT trigger anything. **Merging or pushing to `main` never deploys.** Report that the change is on `main` and will deploy when `main` is promoted to `dev` (`/promote main dev`).
+- **On a feature/work branch**: Do NOT trigger. Report that the pipeline will trigger when the work is promoted after the PR merges.
 
 ## Step 6: Report
 
@@ -82,5 +83,5 @@ Deployed successfully.
 
 Branch: {branch}
 Commit: {hash} - {message}
-Pipeline: {triggered | will trigger on PR merge}
+Pipeline: {triggered | none — main deploys nothing; promote to dev | will trigger when promoted after PR merge}
 ```

package/templates/commands/edit-work-item.md

@@ -168,7 +168,7 @@ Show the field-level diff for every story marked **Update**, and the full draft
 
 ## Step 5: Safety Gate — In-Flight Work
 
-Before asking for approval, check the state of everything you propose to write and flag anything that is **past `Dev Ready`** in the workflow (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready to Deploy`, `Deployed`, `Closed`) or has a **linked pull request**.
+Before asking for approval, check the state of everything you propose to write and flag anything that is **past `Dev Ready`** in the workflow (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready for Staging`, `Staging`, `Ready to Deploy`, `Deployed`, `Closed`) or has a **linked pull request**.
 
 Editing the acceptance criteria of a story that is already implemented silently invalidates a PR that was reviewed against the old criteria. So for each such item, call it out explicitly:
 

package/templates/commands/implement.md

@@ -269,8 +269,8 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
    | 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. For every missing cell, prompt the user for a value (real, placeholder, or empty) **before creating the PR**. The PR should not be opened until every environment file is accounted for, or the user explicitly confirms the omission is intentional (e.g., the key is supplied via a pipeline variable group, Key Vault, or App Configuration for that environment).
 
@@ -362,7 +362,7 @@ Wait for the user's response before proceeding. Do NOT create a PR until confirm
 
    If the project's process template does not have a `Code Review` state (the update call returns an invalid-state error), fall back in this order: `Resolved` → `In Review` → leave the current state and warn the user that the state could not be advanced automatically. Do not silently swallow the error.
 
-> **Only the Task ever gets closed — never the parent.** The child Task is closed here, at PR creation (step 4 above). When the PR is later completed/merged, do **not** enable Azure DevOps's "Complete associated work items" option: it transitions *every* linked work item, including the parent this PR is linked to. The parent User Story or Bug stays in `Code Review` until QA/UAT and any sibling Tasks are done.
+> **Only the Task ever gets closed — never the parent.** The child Task is closed here, at PR creation (step 4 above). When the PR is later completed/merged, do **not** enable Azure DevOps's "Complete associated work items" option: it transitions *every* linked work item, including the parent this PR is linked to. The parent User Story or Bug stays in `Code Review` until it is promoted: merging this PR into `main` deploys nothing, and the item advances to `Ready for Testing` → `Testing` → `Staging` → `Deployed` as `/promote` and `/deploy-release` carry it through `dev → test → staging → prod` (see **Work Item States ↔ Environments** in CLAUDE.md).
 
 ### Closing Related Tasks
 

package/templates/commands/plan-sprint.md

@@ -54,7 +54,7 @@ FROM WorkItems
 WHERE [System.TeamProject] = '{project}'
   AND [System.WorkItemType] IN ('User Story', 'Bug')
   AND [System.IterationPath] UNDER '{current sprint iteration path}'
-  AND [System.State] NOT IN ('Closed', 'Removed', 'Done', 'Resolved', 'Code Review', 'Ready to Deploy', 'Deployed')
+  AND [System.State] NOT IN ('Closed', 'Removed', 'Done', 'Resolved', 'Code Review', 'Ready for Testing', 'Testing', 'Ready for Staging', 'Staging', 'Ready to Deploy', 'Deployed')
 ORDER BY [Microsoft.VSTS.Common.StackRank] ASC
 ```
 

package/templates/commands/promote.md

@@ -1,31 +1,48 @@
 Promote all code from one environment to the next. Usage: `/promote [source] [target]`
 
 Parse `$ARGUMENTS` to extract:
-- **Source environment**: optional (e.g., "develop", "staging"). If omitted, auto-detect.
-- **Target environment**: optional. If omitted, use the next environment in the promotion flow.
+- **Source**: optional — an environment or branch name (`main`, `dev`, `test`, `staging`). If omitted, auto-detect from the current branch.
+- **Target**: optional — the environment to promote into. If omitted, use the next row in the promotion flow.
+
+## Environment ↔ State Reference
+
+Resolve branch names from the project's `CLAUDE.md` **Pipeline Configuration** table — never hardcode them. The first row is the compare branch (`main`; feature PRs target it, **merging into it deploys nothing**); the rows below are the environment branches in promotion order, and a PR merging into one of them is what triggers its pipeline:
+
+| Branch | Environment | Gate — items should already be in… | State set after the PR merges |
+|---|---|---|---|
+| `main` | — (compare branch) | — | — |
+| `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: Determine Source and Target
 
-If not specified, auto-detect based on the current branch:
+Read the Pipeline Configuration table. If it is missing, fall back to `git branch -r` and ask the user to confirm the pair. If not specified, auto-detect based on the current branch:
 
 | Current Branch | Source | Target |
 |---|---|---|
-| `develop` | develop | staging |
-| `staging` | staging | production branch |
+| `main` | main | dev |
+| `dev` | dev | test |
+| `test` | test | staging |
+| `staging` | staging | prod |
+| `prod` | — | Nothing above production — report and stop |
+| a feature/work branch | — | Ask which pair to promote |
 
-If both are specified (e.g., `/promote staging production`), use those directly.
+If both are specified (e.g., `/promote staging prod`), use those directly. Accept environment names (`production`, `Dev`) as well as branch names and map them through the table. Refuse to promote **backward** (e.g. `prod → staging`) — that is `/rollback`'s job.
 
-Determine the actual branch names — do NOT hardcode. Check the project's CLAUDE.md or use `git branch -r` to find matching environment branches.
+`main → dev` is the usual first hop: it carries every feature PR that has merged into `main` and gives it its first deployment.
 
 ## Step 2: Show What Will Be Promoted
 
-Compare the source and target branches to show what's new:
-
 ```bash
-git log <target-branch>..<source-branch> --oneline
+git fetch origin <source-branch> <target-branch>
+git log origin/<target-branch>..origin/<source-branch> --oneline
 ```
 
-Present the changes:
+Present the changes, resolving work items from `AB#` references in commit messages (or `repo_search_commits` with `includeWorkItems: true`):
 
 ```
 ## Promote {source} → {target}
@@ -38,14 +55,33 @@ Commits to promote:
 | ghi9012 | Update dashboard | AB#1236 |
 
 {count} commits will be promoted from {source} to {target}.
-Promote? (yes/no)
 ```
 
-If there are no new commits, report that the environments are already in sync.
+If there are no new commits, report that the environments are already in sync and stop.
 
-Wait for confirmation.
+## Step 3: Gate Check
 
-## Step 3: Create PR
+Fetch each referenced work item and compare its `System.State` with the target's gate. Promotion carries **everything** on the source branch, so an item behind the gate can't be dropped — the choice is to proceed, or to stop and use `/deploy-release` / `/cherry-pick` for a subset:
+
+```
+⚠ Gate check for {target} (expects `{gate state}`):
+
+| ID | State | Note |
+|----|-------|------|
+| AB#1236 | Testing | behind — QA hasn't marked it Ready for Staging |
+
+/promote carries the whole branch. Options:
+  1. Promote anyway (AB#1236 goes to {target} too)
+  2. Stop — use /deploy-release or /cherry-pick for just the ready items
+
+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.
+
+Then confirm: `Promote {count} commits from {source} to {target}? (yes/no)` — and wait.
+
+## Step 4: Create PR
 
 Create a PR directly from the source branch to the target branch via Azure DevOps MCP:
 
@@ -54,18 +90,32 @@ Create a PR directly from the source branch to the target branch via Azure DevOp
 - **title**: `Promote {source} → {target}`
 - **description**: List all commits and associated work items being promoted
 
-Link any associated work items to the PR.
+Link the associated work items to the PR.
 
-## Step 4: Present Summary
+## Step 5: Present Summary and Wait for the Merge
 
 ```
 Promotion PR created: {source} → {target}
 
 PR: {pr-url}
 
-{count} commits included.
-Merge the PR to trigger the CD pipeline for {target}.
-Remember to update work item states in Azure DevOps after merge.
+{count} commits, {n} work items included.
+Merging the PR triggers the CD pipeline for {target}.
+
+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.)
 ```
 
 Do NOT merge the PR automatically — the user or a reviewer must approve and merge.
+
+## Step 6: Advance Work Item States (after `merged`)
+
+When the user replies `merged`:
+
+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`.
+   - **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`).
+
+If the user replies `skip`, leave the states alone and note that `/status` will flag the lag later.

package/templates/commands/quote-backlog.md

@@ -372,7 +372,7 @@ Only for approved items, in batch order:
 2. **Send unquotable User Stories back to Design Review** (approved `User Story` items with **no** proposed points, where the blocker is missing information): set `System.State` = `Design Review` via `mcp__azure-devops__wit_update_work_item`. Do this **before** posting the comment in step 4, so the creator's notification arrives with the item already back in their queue. Rules:
 
    - **`User Story` only.** Do not attempt this on a `Bug` or a `Hot Fix` — those types have no `Design Review` state, so the update fails at runtime in the middle of the batch. They take step 3 instead.
-   - Only from `Design Approved` — **never move an item backward past the design stage.** An item at `Dev Ready`, or anything at `Active` or later (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready to Deploy`, …), keeps its state; note it in the summary instead.
+   - Only from `Design Approved` — **never move an item backward past the design stage.** An item at `Dev Ready`, or anything at `Active` or later (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready for Staging`, `Staging`, `Ready to Deploy`, …), keeps its state; note it in the summary instead.
    - Skip items whose only finding is **needs to be split** — the work is understood, so nothing is missing; leave those in `Design Approved`.
    - If the item is already in `Design Review`, this is a no-op — post the comment and move on.
    - If this project's `User Story` type has no `Design Review` state either (the update returns an invalid-state error), fall back in this order: `In Design` → the `needs-info` tag from step 3 → leave the item alone and **warn the user** that it will be picked up again by the next sweep. Do not silently swallow the error.

package/templates/commands/quote.md

@@ -114,7 +114,7 @@ Only update the work item if the user explicitly says yes. Do not modify anythin
 When the user agrees, in the **same** `wit_update_work_item` call:
 
 1. Set `Microsoft.VSTS.Scheduling.StoryPoints` to the agreed value (the user's number wins if they adjusted it).
-2. Set `System.State` to `Dev Ready` — **but only if** the work item type is `User Story`, `Bug`, or `Hot Fix` **and** the item is not already past Dev Ready in the workflow (e.g. `Active`, `Code Review`, `Ready to Deploy`). Never move an item backward — if it's already past Dev Ready, set the points only and mention the state was left alone.
+2. Set `System.State` to `Dev Ready` — **but only if** the work item type is `User Story`, `Bug`, or `Hot Fix` **and** the item is not already past Dev Ready in the workflow (e.g. `Active`, `Code Review`, `Testing`, `Staging`, `Ready to Deploy`). Never move an item backward — if it's already past Dev Ready, set the points only and mention the state was left alone.
 
 **Never change the state of a Feature or a Task** — if the sized item is a Feature, persist points only (or per-child points on the children, each of which does get Dev Ready if it qualifies).
 
@@ -128,7 +128,7 @@ When the item came out of Step 2 as **needs more information**, offer to drop it
 | `Bug`, `Hot Fix` | Add a **`needs-info` tag**; leave the state at `New` | 5b |
 | `Feature`, `Task` | Neither — report the gap and stop | — |
 
-In the CSI Development process template, `Bug` and `Hot Fix` have **no design states at all** — the workflow is `New` → `Dev Ready` → `Active` → `Code Review` → …, with neither `Design Review` nor `Design Approved`. `New` is the bottom of that workflow, so there is nowhere to send a bug back to; the tag is what keeps `/quote-backlog` from re-analyzing it. On an unfamiliar project, confirm the type's real states with `mcp__azure-devops__wit_work_item` (`action: get_type`, `workItemType: Bug`) and read the `states` array — don't infer a state name from what the workflow "should" have. A bad state name is accepted by a query (zero rows, no error) and rejected only at write time.
+In the CSI Development process template, `Bug` and `Hot Fix` have **no design states at all** — the workflow is `New` → `Dev Ready` → `Active` → `Code Review` → `Ready for Testing` → `Testing` → `Ready for Staging` → `Staging` → `Ready to Deploy` → `Deployed` → `Closed`, with neither `Design Review` nor `Design Approved`. `New` is the bottom of that workflow, so there is nowhere to send a bug back to; the tag is what keeps `/quote-backlog` from re-analyzing it. On an unfamiliar project, confirm the type's real states with `mcp__azure-devops__wit_work_item` (`action: get_type`, `workItemType: Bug`) and read the `states` array — don't infer a state name from what the workflow "should" have. A bad state name is accepted by a query (zero rows, no error) and rejected only at write time.
 
 ### 5a. User Story → Design Review
 
@@ -137,7 +137,7 @@ In the CSI Development process template, `Bug` and `Hot Fix` have **no design st
 **Wait for the user.** Only update the work item if they say yes. Then set `System.State` = `Design Review` with `mcp__azure-devops__wit_update_work_item`. Rules:
 
 - **`User Story` only** — never a Bug, Hot Fix, Feature, or Task. A Bug takes 5b; the update would fail on it anyway.
-- **Never move an item backward past the design stage.** Only from `Design Approved`; if it's already `Dev Ready` or anything at `Active` or later (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready to Deploy`, …), leave the state alone and say so — someone is already working on it, and a state bounce there does real damage.
+- **Never move an item backward past the design stage.** Only from `Design Approved`; if it's already `Dev Ready` or anything at `Active` or later (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready for Staging`, `Staging`, `Ready to Deploy`, …), leave the state alone and say so — someone is already working on it, and a state bounce there does real damage.
 - Already in `Design Review` → no-op; say it's already there.
 - No `Design Review` state for `User Story` in this process template (the update returns an invalid-state error) → fall back in this order: `In Design` → the `needs-info` tag from 5b → leave the state alone and **warn** that the item will keep surfacing in backlog sweeps. Don't swallow the error.
 - Set **no** story points and touch no other field — assignee, iteration, and tags stay as they are.

package/templates/commands/review.md

@@ -52,7 +52,7 @@ Review PR #$ARGUMENTS in the current project. Automatically:
    - Error handling (are exceptions caught appropriately?)
    - Naming conventions and code style consistency
    - Breaking changes or backwards compatibility issues
-   - **Environment configuration parity** — if the diff adds or changes any key in `appsettings.*.json` or `.env*`, every parallel environment file (Development/Staging/QA/Production for backend; `.env.development`/`.env.staging`/`.env.production`/`.env.example` for React) must have a corresponding entry, or the omission must be called out in the PR description. Build a table of (key × environment) and flag any missing cell as **critical**. Pipeline variable groups, Key Vault, or App Configuration wiring counts as a valid source for a given environment — verify it exists rather than assume it.
+   - **Environment configuration parity** — if the diff adds or changes any key in `appsettings.*.json` or `.env*`, every parallel environment file (Development/Test/QA/Staging/Production for backend; `.env.development`/`.env.test`/`.env.staging`/`.env.production`/`.env.example` for React) must have a corresponding entry, or the omission must be called out in the PR description. Build a table of (key × environment) and flag any missing cell as **critical**. Pipeline variable groups, Key Vault, or App Configuration wiring counts as a valid source for a given environment — verify it exists rather than assume it.
    - **Rework-specific (if applicable):** does this diff fully address every item in the rework feedback? Does it regress anything that prior merged PRs delivered?
 
 6. **Draft (do not post yet) the inline comments** for every finding. For each, capture: file path, line number, severity, and the exact comment body you intend to post.

package/templates/commands/rework.md

@@ -264,7 +264,7 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
 1. **Run the full test suite** — every unit test in the repo, plus integration tests. Not just the tests added in this rework. A failure in an unrelated test means this rework broke something else; treat it as a regression, fix it, and re-run until the entire suite is green
 2. **Run lint** — ESLint and dotnet format
-3. **Environment configuration parity** — if the rework added or changed any key in `appsettings.*.json` or `.env*`, verify every parallel environment file (Development/Staging/QA/Production for backend; `.env.development`/`.env.staging`/`.env.production`/`.env.example` for React — whichever exist in the repo) has a corresponding entry. Present a (key × environment) table. Prompt the user to fill in any missing values (real, placeholder, or empty) **before pushing**, or to explicitly confirm the omission is intentional (e.g., supplied via a pipeline variable group, Key Vault, or App Configuration).
+3. **Environment configuration parity** — if the rework added or changed any key in `appsettings.*.json` or `.env*`, verify every parallel environment file (Development/Test/QA/Staging/Production for backend; `.env.development`/`.env.test`/`.env.staging`/`.env.production`/`.env.example` for React — whichever exist in the repo) has a corresponding entry. Present a (key × environment) table. Prompt the user to fill in any missing values (real, placeholder, or empty) **before pushing**, or to explicitly confirm the omission is intentional (e.g., supplied via a pipeline variable group, Key Vault, or App Configuration).
 4. **Acceptance Criteria check** — re-read the work item's full Acceptance Criteria (the same list captured in Step 3). For each AC, identify the test or piece of code that proves it's met. If any AC has no covering test or visible code path, flag it before moving on.
 
    > **Ultracode (if opted in):** Fan out this check with `Workflow` — one read-only agent per acceptance criterion, each returning `{ac, covered: bool, evidence, gap?}`. Collect the results in the main loop and act on any `covered: false`.
@@ -350,7 +350,7 @@ Wait for the user's response before proceeding. Do NOT push until confirmed.
 
    If the project's process template does not have a `Code Review` state (the update call returns an invalid-state error), fall back in this order: `Resolved` → `In Review` → leave the current state and warn the user. Do not silently swallow the error.
 
-> **PR completion closes the Task only.** When the PR is later completed/merged, only the child **Task** may be closed — never the parent User Story or Bug. Azure DevOps's "Complete associated work items" option transitions *every* linked work item (including the parent the PR is linked to), so do **not** enable it when completing the PR. Close the child Task explicitly instead; the parent stays in `Code Review` until QA/UAT and any sibling Tasks are done.
+> **PR completion closes the Task only.** When the PR is later completed/merged, only the child **Task** may be closed — never the parent User Story or Bug. Azure DevOps's "Complete associated work items" option transitions *every* linked work item (including the parent the PR is linked to), so do **not** enable it when completing the PR. Close the child Task explicitly instead; the parent stays in `Code Review` until it is promoted through `dev → test → staging → prod` (see **Work Item States ↔ Environments** in CLAUDE.md).
 
 ### Closing Related Tasks
 

package/templates/commands/rollback.md

@@ -2,11 +2,11 @@ Roll back a deployment in an environment. Usage: `/rollback <work-item-ids-or-co
 
 Parse `$ARGUMENTS` to extract:
 - **What to revert**: work item IDs (e.g., "AB#1234") or commit hashes, or "last" for the most recent deployment
-- **Target environment**: the environment to roll back (e.g., "staging", "production")
+- **Target environment**: the environment to roll back (`dev`, `test`, `staging`, `prod`/`production`)
 
 ## Step 1: Identify What to Revert
 
-Determine the target environment branch. Do NOT hardcode branch names.
+Determine the target environment branch from the project's `CLAUDE.md` **Pipeline Configuration** table (`dev`, `test`, `staging`, `prod`). Do NOT hardcode branch names. `main` is the compare branch, not an environment — reverting there deploys nothing; if the user asks to roll back `main`, explain that and ask which environment they actually mean (or confirm they want the code removed from `main` too, so it doesn't come back on the next promotion).
 
 If the user specified:
 - **Work item IDs**: Find the associated commits on the environment branch using `repo_search_commits` with `includeWorkItems: true`
@@ -86,9 +86,13 @@ Reverted:
 - AB#1235: Fix login redirect
 
 Merge the PR to trigger the CD pipeline and deploy the rollback.
+
+Work items reverted from {environment}: AB#1234, AB#1235 — their state still says `{current state}`.
+The fix will need to go through main → dev → test → staging → prod again, so move them back to `Active`
+(or leave them and open a new Bug) — your call; I won't change states on a rollback.
 ```
 
-For production rollbacks, flag urgency to the user.
+For production rollbacks, flag urgency to the user. If the reverted commits are also on `main` (they usually are), remind the user that the next `/promote` will bring them back unless the revert is also applied to `main` — offer `/cherry-pick` of the revert commit to `main`.
 
 ## Step 7: Notify Team (if Teams MCP is configured)