@chris1807/claude-kit 2.1.54 → 2.1.56

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.
+
+## Step 3: Gate Check
+
+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.
 
-Wait for confirmation.
+Then confirm: `Promote {count} commits from {source} to {target}? (yes/no)` — and wait.
 
-## Step 3: Create PR
+## Step 4: Create PR
 
 Create a PR directly from the source branch to the target branch via Azure DevOps MCP:
 
@@ -54,18 +90,141 @@ 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 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.
 
-## Step 4: Present Summary
+### 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}
 
 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}. 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`.
+
+**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 7: 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 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.
+   - 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.
+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"}.
 ```
 
-Do NOT merge the PR automatically — the user or a reviewer must approve and merge.
+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.

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)
 

package/templates/commands/status.md

@@ -1,63 +1,96 @@
-Check the status of a release, pipeline, or work item. Usage: `/status <target>`
+Check the status of a release, pipeline, environment, or work item. Usage: `/status <target>`
 
 Parse `$ARGUMENTS` to determine what to check:
 - **Release**: "release 24" or "r24" → show release status
 - **Pipeline**: "pipeline" or "build" → show recent pipeline runs
 - **Work item**: "AB#1234" or "1234" → show work item status
-- **Environment**: "staging" or "production" → show what's deployed
+- **Environment**: "dev", "test", "staging", or "prod" → show what's deployed
 - **No argument**: show an overview of everything
 
+Read the project's `CLAUDE.md` **Pipeline Configuration** table for the branch chain. The first row is the compare branch (`main` — feature PRs merge there; **nothing deploys from it**); the rows below are environment branches in promotion order (`dev → test → staging → prod`). Do not hardcode branch names.
+
+## Environment ↔ State Reference
+
+Work item states track environments. Use this to spot **state lag** — an item whose commits are on a branch but whose state hasn't caught up:
+
+| Commits are on… | State should be at least… |
+|---|---|
+| `main` | `Code Review` |
+| `dev` | `Ready for Testing` |
+| `test` | `Testing` |
+| `staging` | `Staging` |
+| `prod` | `Deployed` |
+
+`Ready for Staging` and `Ready to Deploy` are human sign-offs and are never "lag". Only User Stories, Bugs, and Hot Fixes are checked — Features and Tasks have no environment state.
+
 ## If Release (e.g., `/status release 24`):
 
-Query all work items tagged `release-{N}` or in the `Release #{N}` iteration.
+Query all work items tagged `release-{N}` or in the `Release #{N}` iteration. For each, find which environment branches contain its commits (`repo_search_commits` with `includeWorkItems: true`, or `git merge-base --is-ancestor`).
 
 ```
 ## Release #24 Status
 
-| ID | Type | Title | State | Environment |
-|----|------|-------|-------|-------------|
-| AB#4521 | User Story | Add payment export | Closed | Production |
-| AB#4522 | User Story | Bulk approval workflow | Ready for Testing | Staging |
-| AB#4530 | User Story | Dashboard trends | Ready for Testing | Staging |
+| ID | Type | Title | State | Furthest Environment |
+|----|------|-------|-------|----------------------|
+| AB#4521 | User Story | Add payment export | Deployed | Production |
+| AB#4522 | User Story | Bulk approval workflow | Staging | Staging |
+| AB#4530 | User Story | Dashboard trends | Testing | Staging ⚠ |
 | AB#4589 | Bug | Login plus sign fix | Closed | Production |
 
 Deployed to:
 - Dev: All 4 items
+- Test: All 4 items
 - Staging: All 4 items
 - Production: 2 of 4 items (AB#4521, AB#4589)
+
+⚠ State lag:
+- AB#4530 is on `staging` but still in `Testing` — expected at least `Staging`.
+
+Catch these up? (yes/no)
 ```
 
+If the user says yes, set `System.State` on each lagging item to the expected state via `wit_update_work_item` — never backward, never on a Feature or Task — and report `Was → Now`.
+
 ## If Pipeline (e.g., `/status pipeline` or `/status build`):
 
-Check the project's CLAUDE.md for pipeline configuration. Query recent builds for each pipeline.
+Query recent builds for each pipeline in the Pipeline Configuration table.
 
 ```
 ## Recent Pipeline Runs
 
 | Pipeline | Branch | Status | Time | Build # |
 |----------|--------|--------|------|---------|
-| Compass API | main | Succeeded | 2026-03-22 14:26 | 20260322.1 |
-| Compass Client | main | Succeeded | 2026-03-22 14:27 | 20260322.1 |
-| Compass API | develop | Succeeded | 2026-03-21 10:15 | 20260321.3 |
+| Compass API (YAML) | prod | Succeeded | 2026-09-06 14:26 | 20260906.1 |
+| Compass Client (YAML) | prod | Succeeded | 2026-09-06 14:27 | 20260906.1 |
+| Compass API (YAML) | test | Succeeded | 2026-09-05 10:15 | 20260905.3 |
 ```
 
+A run on `main` would be unexpected — `main` has no pipeline. If one appears, say so.
+
 ## If Work Item (e.g., `/status AB#4521`):
 
-Read the work item from Azure DevOps and show its full status.
+Read the work item from Azure DevOps and show its full status, including which environment branches contain its commits.
 
 ```
 ## AB#4521: Admin Can Export Payment History to CSV
 
 **Type:** User Story
-**State:** Ready for Testing
+**State:** Staging
 **Assigned To:** Chris Waters
 **Release:** Release #24
 **Branch:** story/AB#4521-admin-can-export-payment-history
-**PR:** #287 (merged to develop)
+**PR:** #287 (merged to main)
 
-### Linked PRs
-- PR #287 → develop (merged 2026-03-20)
-- PR #291 → staging (merged 2026-03-21)
+### Environments
+| Environment | Branch | Present |
+|-------------|--------|---------|
+| — (compare) | main | Yes — PR #287 merged 2026-09-01 |
+| Dev | dev | Yes — PR #290 merged 2026-09-02 |
+| Test | test | Yes — PR #291 merged 2026-09-03 |
+| Staging | staging | Yes — PR #295 merged 2026-09-05 |
+| Production | prod | No |
+
+State `Staging` matches the furthest environment. ✓
 
 ### Child Tasks
 | ID | Title | State |
@@ -67,24 +100,31 @@ Read the work item from Azure DevOps and show its full status.
 | AB#4527 | Add export button UI | Closed |
 ```
 
+If the state lags the furthest environment, flag it and offer to catch it up as in the release view.
+
 ## If Environment (e.g., `/status staging`):
 
-Check the project's CLAUDE.md for the environment branch mapping. Show the last deployment and what's currently deployed.
+Map the name to its branch through the Pipeline Configuration table. Show the last deployment and what's currently there.
 
 ```
 ## Staging Environment
 
 **Branch:** staging
-**Last deployment:** 2026-03-21 15:30 (Build #20260321.2)
-**Pipeline:** Compass API — Succeeded
+**Last deployment:** 2026-09-05 15:30 (Build #20260905.2)
+**Pipeline:** Compass API (YAML) — Succeeded
 
 ### Recent merges to staging:
 | Commit | Message | Date |
 |--------|---------|------|
-| a1b2c3d | Release #24 → Staging | 2026-03-21 |
-| d4e5f6a | Cherry-pick AB#4601 | 2026-03-22 |
+| a1b2c3d | Release #24 → Staging | 2026-09-05 |
+| d4e5f6a | Cherry-pick AB#4601 → Staging | 2026-09-06 |
+
+### Not yet promoted from test:
+{count} commits on `test` are not on `staging` — run `/promote test staging` or `/deploy-release <N> staging`.
 ```
 
+`/status main` is allowed but reports "compare branch — nothing deploys from main" and lists what's on `main` that hasn't been promoted to `dev`.
+
 ## If No Argument (e.g., `/status`):
 
 Show a high-level overview.
@@ -93,19 +133,29 @@ Show a high-level overview.
 ## Project Status
 
 ### Active Releases
-| Release | Work Items | Latest Environment |
-|---------|-----------|-------------------|
+| Release | Work Items | Furthest Environment |
+|---------|-----------|----------------------|
 | Release #24 | 6 items | Staging |
 | Release #23 | 4 items | Production |
 
+### Environment Chain
+| Branch | Environment | Behind previous by |
+|--------|-------------|--------------------|
+| main | — (compare) | — |
+| dev | Dev | 0 commits |
+| test | Test | 3 commits |
+| staging | Staging | 3 commits |
+| prod | Production | 9 commits |
+
 ### Recent Pipelines
-| Pipeline | Last Run | Status |
-|----------|----------|--------|
-| Compass API | 20260322.1 | Succeeded |
-| Compass Client | 20260322.1 | Succeeded |
+| Pipeline | Last Run | Branch | Status |
+|----------|----------|--------|--------|
+| Compass API (YAML) | 20260906.1 | prod | Succeeded |
+| Compass Client (YAML) | 20260906.1 | prod | Succeeded |
 
 ### Open PRs
 | PR # | Title | Target |
 |------|-------|--------|
-| #292 | AB#4601: Fix bulk approval | develop |
+| #292 | AB#4601: Fix bulk approval | main |
+| #296 | Promote test → staging | staging |
 ```

package/templates/commands/where.md

@@ -12,14 +12,16 @@ Capture: id, title, type, state, and any linked Pull Request artifacts from `rel
 
 ## Step 2: Resolve the Environment Chain
 
-Read the **Pipeline Configuration** table from the current repo's `CLAUDE.md`. The table rows define the environment branches in promotion order (top → bottom). Example:
+Read the **Pipeline Configuration** table from the current repo's `CLAUDE.md`. The table rows define the branches in promotion order (top → bottom). The **first row is the compare branch** (`main`) — feature PRs merge there, but nothing deploys from it; the rows below are the environment branches. Example:
 
 ```
 | Branch | Environment | Pipeline(s) |
 |--------|------------|-------------|
-| develop | Dev | ... |
+| main | — (compare branch, no deployment) | — |
+| dev | Dev | ... |
+| test | Test | ... |
 | staging | Staging | ... |
-| main | Production | ... |
+| prod | Production | ... |
 ```
 
 If the table is missing, report that the project has no pipeline configuration in `CLAUDE.md` and stop.
@@ -62,19 +64,21 @@ AB#<id>: <title>
 This work item is in <env list joined with " and ">.
 ```
 
-Where `<env list>` is the environments where the work item is present, in promotion order. If none, say "not deployed to any environment yet."
+Where `<env list>` is the environments where the work item is present, in promotion order. The compare branch is not an environment: if the commits are on `main` only, say "merged to main, not deployed to any environment yet." If not even on `main`, say "not merged yet."
 
 Then a details table:
 
 ```
-| Environment | Branch  | Deployed | Commits |
-|-------------|---------|----------|---------|
-| Dev         | develop | Yes      | 2 of 2  |
-| Staging     | staging | Yes      | 2 of 2  |
-| Production  | main    | No       | 0 of 2  |
+| Environment | Branch  | Present | Commits |
+|-------------|---------|---------|---------|
+| — (compare) | main    | Yes     | 2 of 2  |
+| Dev         | dev     | Yes     | 2 of 2  |
+| Test        | test    | Yes     | 2 of 2  |
+| Staging     | staging | Yes     | 1 of 2  |
+| Production  | prod    | No      | 0 of 2  |
 ```
 
-- **Deployed**: Yes if at least one commit is reachable from the branch tip; No otherwise.
+- **Present**: Yes if at least one commit is reachable from the branch tip; No otherwise. For the compare branch this means "merged", not "deployed".
 - **Commits**: how many of the work item's commits are present on that branch (e.g. `1 of 2` flags a partial cherry-pick).
 
 If any linked PRs are still open (not merged), append:
@@ -84,4 +88,6 @@ Open PRs:
 - PR #<n> → <target branch> (<status>)
 ```
 
-That's it — read-only. Do not modify branches, push, or create PRs.
+Finally, compare the work item's state with its furthest environment (`dev` → `Ready for Testing`, `test` → `Testing`, `staging` → `Staging`, `prod` → `Deployed`). If the state lags — e.g. commits on `staging` but the item is still `Testing` — add one line: `⚠ State lags environment: Testing, expected at least Staging — /status AB#<id> can catch it up.`
+
+That's it — read-only. Do not modify branches, push, create PRs, or change states.