@chris1807/claude-kit 2.1.54 → 2.1.56

package/templates/commands/cleanup-branches.md

@@ -12,9 +12,9 @@ git branch -r --merged
 ```
 
 Exclude protected branches — never delete these:
-- `main`, `master`, `develop`, `development`
-- `staging`, `Staging`
-- `Dev`, `QA`
+- The compare branch: `main`, `master`
+- The environment branches: `dev`, `test`, `staging`, `prod` (any casing — `Dev`, `Test`, `Staging`, `Prod`)
+- Legacy names still in use on unmigrated projects: `develop`, `development`, `QA`
 - Any branch listed in the project's CLAUDE.md Pipeline Configuration table
 
 ## Step 2: Identify Candidates
@@ -33,13 +33,13 @@ Present the list:
 ### Branches to delete ({count}):
 | Branch | Last Commit | Merged Into |
 |--------|-------------|-------------|
-| story/AB#4521-admin-export | 2026-03-18 | develop |
-| bugfix/AB#4589-login-plus-sign | 2026-03-19 | develop |
-| release/24-to-staging | 2026-03-21 | staging |
-| cherry-pick/2026-03-22-to-production | 2026-03-22 | main |
+| story/AB#4521-admin-export | 2026-09-01 | main |
+| bugfix/AB#4589-login-plus-sign | 2026-09-02 | main |
+| release/24-to-staging | 2026-09-05 | staging |
+| cherry-pick/2026-09-06-to-prod | 2026-09-06 | prod |
 
 ### Protected (will NOT be deleted):
-- main, develop, staging
+- main, dev, test, staging, prod
 
 Delete {count} merged branches? (yes/no)
 ```
@@ -69,5 +69,5 @@ Deleted:
 - story/AB#4521-admin-export (local + remote)
 - bugfix/AB#4589-login-plus-sign (local + remote)
 - release/24-to-staging (remote only)
-- cherry-pick/2026-03-22-to-production (remote only)
+- cherry-pick/2026-09-06-to-prod (remote only)
 ```

package/templates/commands/create-release.md

@@ -11,7 +11,7 @@ If `$ARGUMENTS` is provided, use it as the release name (e.g., `$ARGUMENTS` = "2
 Ask the user which work items to include. They may provide:
 - A list of work item IDs (e.g., "AB#1234, AB#1235, AB#1236")
 - A query (e.g., "all completed user stories in the current sprint")
-- A state filter (e.g., "all items in Ready for Testing")
+- A state filter (e.g., "all items in Ready for Testing" for a release heading to Test, "all items in Ready for Staging" for one heading to Staging)
 
 Use the Azure DevOps MCP to search/query for the specified work items. Present the list for confirmation:
 
@@ -60,6 +60,9 @@ Work items assigned:
 - AB#1235: Fix login redirect
 - AB#1236: View history
 
-To deploy this release to staging:  /deploy-release {N} staging
-To deploy this release to production: /deploy-release {N} production
+Deploy it one environment at a time — each merge deploys, and once the pipeline is green the command advances the work items' states and assigns them to the verifiers you pick:
+  /deploy-release {N} test      → items go to Testing
+  /deploy-release {N} staging   → items go to Staging   (after QA sets Ready for Staging)
+  /deploy-release {N} prod      → items go to Deployed  (after stakeholders set Ready to Deploy)
+`/deploy-release {N}` with no environment picks the next one automatically.
 ```

package/templates/commands/deep-review.md

@@ -111,7 +111,7 @@ Verify the change is safe beyond the lines it touched.
 Specifically check:
 - **Changed shared code** — for every public method/class/interface/DTO the diff modifies, find its other callers and confirm the change is backward-compatible or all callers were updated.
 - **Test fallout** — any failing test from Step 4 in an area this PR didn't intend to change is a regression; surface it as **critical**.
-- **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. Build a (key × environment) table and flag any missing cell as **critical**. A pipeline variable group, Key Vault, or App Configuration counts as a valid source for an 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. Build a (key × environment) table and flag any missing cell as **critical**. A pipeline variable group, Key Vault, or App Configuration counts as a valid source for an environment — verify it exists rather than assume it.
 
 ## Step 7: Detect Unwanted / Out-of-Scope Changes — and Confirm With the User
 

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

package/templates/commands/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
 ```