@chris1807/claude-kit 2.1.55 → 2.1.57

package/README.md

@@ -181,6 +181,7 @@ The installer automatically **skips global agents** that are already installed (
 ├── mockup.md                      # HTML mockup designer
 ├── reviewer.md                    # Code reviewer (read-only)
 ├── test-runner.md                 # Test executor — xUnit, Vitest, Playwright (read-only)
+├── qa.md                          # Browser QA on a deployed environment (read-only)
 ├── build-validator.md             # Build checker (read-only)
 ├── lint-checker.md                # ESLint + dotnet format checker
 ├── azure-ops.md                   # Azure infrastructure management
@@ -329,7 +330,8 @@ Claude automatically:
 2. Cherry-picks their commits into `release/23-to-staging`
 3. Creates a PR targeting the `staging` branch — merging it triggers the Staging pipeline
 4. Links all work items to the PR
-5. After you reply `merged`, moves the work items to `Staging`
+5. Asks who verifies each product group on Staging (`COM`, `PAY`, …) — candidates are the non-developer names already on those work items
+6. Watches the PR and the Staging pipeline; once it's green, moves the work items to `Staging` and assigns them to the approved verifiers
 
 The same command walks a release through `test` → `staging` → `prod`; with no environment given it picks the next one.
 
@@ -339,7 +341,7 @@ The same command walks a release through `test` → `staging` → `prod`; with n
 /cherry-pick AB#1234 AB#1235 prod
 ```
 
-Cherry-picks specific work items to an environment without a formal release. Same gate check and post-merge state advance as `/deploy-release`. `main` is also a valid target — that's how a hot fix that went straight to `prod` is brought back into the compare branch.
+Cherry-picks specific work items to an environment without a formal release. Same gate check, same verifier question, and the same automatic state advance + assignment once the pipeline is green as `/deploy-release`. `main` is also a valid target — that's how a hot fix that went straight to `prod` is brought back into the compare branch.
 
 ### Promote an Environment
 
@@ -349,7 +351,7 @@ Cherry-picks specific work items to an environment without a formal release. Sam
 /promote                  ← auto-detects from the current branch
 ```
 
-Creates a PR to promote all code from one branch to the next in the chain (`main → dev → test → staging → prod`). Shows every commit and work item before confirming, gate-checks the work items, and advances their states after you reply `merged`. `main → dev` is the usual first hop after feature PRs merge — nothing has deployed before that.
+Creates a PR to promote all code from one branch to the next in the chain (`main → dev → test → staging → prod`). Shows every commit and work item before confirming, gate-checks the work items, asks who verifies each product group, and advances and assigns them once the merge's pipeline is green. `main → dev` is the usual first hop after feature PRs merge — nothing has deployed before that.
 
 ### Rollback a Deployment
 
@@ -439,7 +441,7 @@ Every environment has a work item state, and the promotion commands keep them in
 | `test → staging` | `Ready for Staging` (QA sign-off) | `Staging` |
 | `staging → prod` | `Ready to Deploy` (stakeholder sign-off) | `Deployed` |
 
-`/deploy-release`, `/cherry-pick`, and `/promote` check the gate before creating the PR, then ask you to reply `merged` once the PR completes and advance the states. `/status` flags anything whose state lags the branch it's on.
+`/deploy-release`, `/cherry-pick`, and `/promote` check the gate before creating the PR, ask who verifies each product group while the PR is in review, then watch the PR and the environment's CD pipeline — on a green pipeline they set the state and the assignee together. A failed pipeline changes nothing. `/status` flags anything whose state lags the branch it's on.
 
 ### Branch Naming
 
@@ -507,7 +509,7 @@ The PR merges into `main`. **That merge deploys nothing** — `main` is the comp
 /promote main dev
 ```
 
-Merge that PR, reply `merged`, and the work items move to `Ready for Testing`.
+Merge that PR. Claude asks who verifies each product group on Dev, watches the Dev pipeline, and once it's green moves the work items to `Ready for Testing` and assigns them to those people.
 
 ### Step 2: Deploy Changes (Quick Commits)
 
@@ -550,7 +552,8 @@ Claude will:
 4. Cherry-pick all commits for each work item
 5. Create a PR from `release/23-to-test` → `test`
 6. Link all work items to the PR
-7. After you reply `merged`, move the work items to `Testing`
+7. Ask who verifies each product group on Test
+8. Watch the PR and the Test pipeline; on a green pipeline, move the work items to `Testing` and assign them to the approved verifiers
 
 After the PR is reviewed and merged, the Test CD pipeline triggers automatically. QA tests there and sets each passing item to `Ready for Staging`; then `/deploy-release 23 staging` repeats the process (gate `Ready for Staging`, state after merge `Staging`).
 
@@ -566,7 +569,7 @@ When stakeholders have verified on Staging and set the items to `Ready to Deploy
 /deploy-release 23 prod
 ```
 
-Same process — gate `Ready to Deploy`, cherry-picks from `staging` into a PR targeting `prod`. After merge, the Production CD pipeline triggers; reply `merged` and the items move to `Deployed`.
+Same process — gate `Ready to Deploy`, cherry-picks from `staging` into a PR targeting `prod`. After merge the Production CD pipeline triggers; when it comes back green the items move to `Deployed` and are assigned to whoever you named for each product group.
 
 ### Selective Deployment
 
@@ -671,12 +674,13 @@ Claude reviews for:
 | `/fix-review` | `/fix-review 142` | Fix everything flagged on a PR — human reviewer comments and automated `/review` findings alike: implement in severity order, validate, push, resolve threads |
 | `/deploy` | `/deploy "message"` | Commit, push, trigger pipeline if on an environment branch (`dev`/`test`/`staging`/`prod`) — never on `main` |
 | `/create-release` | `/create-release 23` | Group work items into Release #23 iteration with tags |
-| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → cherry-pick release work items to environment via PR → advance states after `merged` |
+| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → cherry-pick release work items to environment via PR → ask who verifies → advance + assign on a green pipeline |
 | `/add-to-release` | `/add-to-release 24 AB#4599` | Add work items to an existing release |
-| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → cherry-pick specific work items to environment via PR → advance states after `merged` |
-| `/promote` | `/promote main dev` | PR to promote all code to the next branch in the chain (`main → dev → test → staging → prod`) → advance states after `merged` |
+| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → cherry-pick specific work items to environment via PR → ask who verifies → advance + assign on a green pipeline |
+| `/promote` | `/promote main dev` | PR to promote all code to the next branch in the chain (`main → dev → test → staging → prod`) → ask who verifies → advance + assign on a green pipeline |
 | `/rollback` | `/rollback AB#1234 prod` | Revert specific commits on an environment via PR |
 | `/status` | `/status release 24` | Check status of a release, pipeline, work item, or environment; flags work items whose state lags their environment |
+| `/qa` | `/qa AB#1234 [env]` | Verify the item is fully deployed with a green pipeline → open the app in a real browser → sign in as a test account → full regression of the screens the story touched → pass/fail comment on the work item (never a state change). Environments: `local`, `dev`, `test`, `staging` |
 | `/plan-backlog` | `/plan-backlog [project]` | Sweep backlog for Dev Ready stories with points and no tasks → propose one child task with hours per story |
 | `/plan-sprint` | `/plan-sprint [project]` | Sweep the current sprint for stories/bugs with no child tasks → propose one child task with hours per item |
 | `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for unpointed items ready to estimate — stories in `Design Approved`, bugs in `New` (bugs have no design states) → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated). Also audits the drop-out queue — tagged bugs and stories bounced to Design Review — for items whose creator answered but which nobody returned to the sweep |
@@ -729,6 +733,12 @@ export STRIPE_SECRET_KEY="sk_test_..."
 # Azure CLI (no env var needed — just log in)
 az login
 
+# QA test accounts (required for /qa — browser testing on a deployed environment).
+# One pair per role. The variable NAMES go in your project's `## Environment URLs`
+# section; the VALUES live only here. Use throwaway least-privilege QA accounts.
+export COMPASS_QA_ADMIN_USERNAME="qa-admin@example.com"
+export COMPASS_QA_ADMIN_PASSWORD="..."
+
 # Microsoft Teams (no env vars needed — uses Microsoft Graph device-code auth;
 # first invocation prints a code + URL to sign in)
 ```

package/bin/cli.js

@@ -161,6 +161,74 @@ function mergeHooks(existing, template) {
 // don't linger. manager/uat-generator/api-tester were superseded by the
 // Workflow tool and inline command steps; devops-tracker by direct Azure
 // DevOps MCP access in the main loop.
+// The workflow section written into a target CLAUDE.md is delimited by this marker so
+// a re-install can replace it without touching anything the project added afterwards.
+// Installs from before the marker existed are recovered heuristically — see
+// splitWorkflowSection.
+const WORKFLOW_END_MARKER = '<!-- claude-kit:workflow:end -->';
+
+const WORKFLOW_HEADING_RE = /\n## (?:Claude Kit Workflow|Care Solutions AI Workflow)/;
+
+/**
+ * Split a target CLAUDE.md around the kit's workflow section.
+ *
+ * Returns { head, preserved } where `head` is everything before the workflow
+ * heading and `preserved` is project content that followed the kit's block —
+ * or null when there is no workflow section at all.
+ *
+ * The old implementation replaced /heading[\s\S]*$/, i.e. everything to end of
+ * file, which silently deleted any `## Pipeline Configuration` or
+ * `## Environment URLs` a project had placed below the heading. With the marker
+ * present the boundary is exact. Without it (a pre-marker install) we fall back
+ * to a heading scan: the template's only top-level heading outside a fenced code
+ * block is the workflow heading itself, so any other non-fenced `## ` heading in
+ * the tail is project content and is kept. Fenced headings are skipped because
+ * the template quotes `## Pipeline Configuration` inside ```markdown examples.
+ */
+function splitWorkflowSection(existing) {
+  const match = existing.match(WORKFLOW_HEADING_RE);
+  if (!match) return null;
+
+  const head = existing.slice(0, match.index).trimEnd();
+  const tail = existing.slice(match.index);
+
+  const markerIdx = tail.indexOf(WORKFLOW_END_MARKER);
+  if (markerIdx !== -1) {
+    return {
+      head,
+      preserved: tail.slice(markerIdx + WORKFLOW_END_MARKER.length).trim(),
+      recovered: false,
+    };
+  }
+
+  const lines = tail.split('\n');
+  // `tail` begins with the newline preceding the heading, so the heading is not at
+  // index 0. Find it explicitly and scan from the line after it — starting at a
+  // fixed offset would treat the heading itself as project content.
+  const headingIdx = lines.findIndex((l) =>
+    /^## (?:Claude Kit Workflow|Care Solutions AI Workflow)/.test(l)
+  );
+  let inFence = false;
+  let cut = -1;
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    if (/^\s*```/.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    if (/^## /.test(lines[i])) {
+      cut = i;
+      break;
+    }
+  }
+
+  return {
+    head,
+    preserved: cut === -1 ? '' : lines.slice(cut).join('\n').trim(),
+    recovered: cut !== -1,
+  };
+}
+
 const RETIRED_GLOBAL_AGENTS = ['manager.md', 'uat-generator.md', 'api-tester.md'];
 const RETIRED_PROJECT_AGENTS = ['devops-tracker.md'];
 
@@ -515,13 +583,16 @@ async function main() {
       'utf8'
     );
 
+    // Delimited so a re-install replaces only the kit's own section.
+    const workflowBlock = `${workflowContent.trimEnd()}\n\n${WORKFLOW_END_MARKER}\n`;
+
     const sensitiveDataPolicy = `## SENSITIVE DATA — MANDATORY RULE
 
 **NEVER query, display, read, grep, or expose sensitive PII fields from the database or codebase — even if the values are encrypted.** Blocked fields: TIN, SSN, EIN, TaxId, BankAccountNumber, RoutingNumber, and any \`Encrypted*\` variants. Always use explicit inclusion projections listing only non-sensitive fields. Direct users to the application UI for sensitive data access.
 `;
 
     if (!await fs.pathExists(claudeMdPath)) {
-      await fs.writeFile(claudeMdPath, `# ${basename(targetDir)}\n\n${sensitiveDataPolicy}\n${workflowContent}`);
+      await fs.writeFile(claudeMdPath, `# ${basename(targetDir)}\n\n${sensitiveDataPolicy}\n${workflowBlock}`);
       console.log(chalk.green('  ✓ Created CLAUDE.md with sensitive data policy and workflow'));
     } else {
       let existing = await fs.readFile(claudeMdPath, 'utf8');
@@ -547,8 +618,22 @@ async function main() {
       if (existing.includes('Claude Kit Workflow') || existing.includes('Care Solutions AI Workflow')) {
         // Check whether the existing workflow section matches the current template.
         // If it does, nothing to do. If not, replace it (auto in --all, prompt otherwise).
-        const cleaned = existing.replace(/\n## (?:Claude Kit Workflow|Care Solutions AI Workflow)[\s\S]*$/, '').trimEnd();
-        const expected = `${cleaned}\n\n${workflowContent}`;
+        const split = splitWorkflowSection(existing);
+        const { head, preserved, recovered } = split;
+        const expected = preserved
+          ? `${head}\n\n${workflowBlock}\n${preserved}\n`
+          : `${head}\n\n${workflowBlock}`;
+        if (recovered && preserved) {
+          const names = (preserved.match(/^## .*$/gm) || []).map((h) => h.replace(/^##\s*/, ''));
+          console.log(
+            chalk.yellow(
+              `  ! Kept project content found below the workflow section: ${names.join(', ') || 'unlabelled section'}`
+            )
+          );
+          console.log(
+            chalk.gray('    It now sits after the end marker, so future updates will leave it alone.')
+          );
+        }
         if (existing.trim() === expected.trim()) {
           console.log(chalk.gray('  = Workflow section up to date'));
         } else if (installAll) {
@@ -569,7 +654,7 @@ async function main() {
           }
         }
       } else {
-        await fs.appendFile(claudeMdPath, `\n\n${workflowContent}`);
+        await fs.appendFile(claudeMdPath, `\n\n${workflowBlock}`);
         console.log(chalk.green('  ✓ Workflow appended to CLAUDE.md'));
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.55",
+  "version": "2.1.57",
   "description": "Claude Code starter kit for Azure DevOps teams — agents, hooks, MCP servers, slash commands, and end-to-end work item → PR → release → deploy workflow automation",
   "type": "module",
   "bin": {

package/templates/agents/global/qa.md

@@ -0,0 +1,136 @@
+---
+name: qa
+description: Regression-tests a work item in a real browser via Playwright MCP. Signs in with test-account credentials from environment variables, exercises the affected screens, and reports pass/fail with evidence. Read-only against the codebase and against Azure DevOps.
+tools: Read, Glob, Grep, Bash, mcp__playwright__browser_navigate, mcp__playwright__browser_navigate_back, mcp__playwright__browser_snapshot, mcp__playwright__browser_find, mcp__playwright__browser_click, mcp__playwright__browser_type, mcp__playwright__browser_fill_form, mcp__playwright__browser_select_option, mcp__playwright__browser_press_key, mcp__playwright__browser_hover, mcp__playwright__browser_wait_for, mcp__playwright__browser_resize, mcp__playwright__browser_handle_dialog, mcp__playwright__browser_console_messages, mcp__playwright__browser_network_requests, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_tabs, mcp__playwright__browser_close
+disallowedTools: Write, Edit
+model: sonnet
+---
+
+# QA Agent
+
+You test a work item in a real browser against a running environment, then report what you found. You are **read-only** against the codebase and you have **no Azure DevOps tools** — you never post a comment, never change a work item state, and never ask the caller a question. You return one report; the main loop does the writing.
+
+## Tools you deliberately do not have
+
+Do not work around these. If a check genuinely needs one, report the check as `NOT TESTABLE` and say which capability was missing.
+
+| Missing | Why it was withheld |
+|---|---|
+| `browser_evaluate`, `browser_run_code_unsafe` | Arbitrary page JS could read any DOM value and defeat every rule below. The omission is the enforcement. |
+| `browser_network_request` (singular) | It returns full request and response bodies — the likeliest route for a TIN or SSN into a transcript. Use `browser_network_requests` (plural), which gives method, URL, and status. |
+| `browser_file_upload`, `browser_drag`, `browser_drop` | Not needed by the checklist below. |
+| Any `mcp__azure-devops__*` tool | You must be structurally unable to advance a work item. |
+| `Write`, `Edit` | You test the app; you never change the code. |
+
+## What you are given
+
+The caller passes a brief containing: the work item id, title, type and state; the target environment name and its App URL (and API URL if known); a **baseline** environment URL for differential re-checks; the sign-in descriptor; the **names** of the environment variables holding the test account credentials; the ordered list of screens with each screen's changed files; and the acceptance criteria.
+
+You are never given a password. You read it yourself.
+
+## Signing in
+
+1. Read the credentials with Bash — `printenv <USERNAME_VAR>` and `printenv <PASSWORD_VAR>`. If either is empty, stop immediately and report `BLOCKED — <VAR> is not set`.
+2. `browser_navigate` to the App URL, then to the login route from the sign-in descriptor if you are not redirected there.
+3. Fill both fields in **one** `browser_fill_form` call, then submit. One call, not two `browser_type` calls — the credential should appear once.
+4. Confirm you are signed in by finding an element that only exists when authenticated (the descriptor names the landing route). If you land back on the login form, stop and report `BLOCKED — sign-in failed`. Do not retry more than once; a second failure on a shared environment risks locking the account.
+5. If the browser is redirected to an external identity provider (`login.microsoftonline.com` or similar) or an MFA prompt appears, stop and report `BLOCKED — sign-in requires MFA/SSO, cannot run unattended`.
+
+**Never** echo, log, repeat, screenshot, or include either credential value in your report. Never write one to a file.
+
+## Regression Method
+
+Work the screens in the order given. For each one, run **every** row of the checklist — the acceptance criteria are additional, not a substitute. Record a result per row before moving on.
+
+| # | Test | How | Expected |
+|---|------|-----|----------|
+| 1 | Route loads | `browser_navigate` to the route | Renders. No error boundary, no blank region |
+| 2 | Deep link | Navigate straight to the URL rather than clicking through | Route rehydrates; no bounce to login, no 404 |
+| 3 | Console clean | `browser_console_messages` | No uncaught errors. React key/prop warnings are noted, not failed |
+| 4 | Network clean | `browser_network_requests` | No 4xx/5xx to the API. Record `METHOD path → status` only |
+| 5 | Data or empty state | `browser_snapshot` | Rows render, **or** an explicit empty-state message. A blank region is a **fail** |
+| 6 | Filters, search, sort | Exercise each control once | Result set changes, no error, control reflects its state |
+| 7 | Pagination | Next, then previous | Content changes; the indicator tracks |
+| 8 | Form — invalid | Submit each form empty | **Inline** validation; nothing submitted |
+| 9 | Form — valid | Submit valid data | Success indication; the list or detail updates |
+| 10 | Form — cancel | Fill, then cancel | No mutation; returns to the prior view |
+| 11 | Dialogs | Open and close each modal and row action | Opens, closes, focus returns. A native `window.confirm`/`alert`/`prompt` is a **fail** |
+| 12 | Back button | Browser back after a mutation | Lands somewhere coherent; no stale or duplicated data |
+| 13 | Responsive | `browser_resize` to 1440, then 768 | No overlap, no clipped controls, no horizontal scroll |
+| 14 | Role gating | If a second role's credentials are named in the brief, sign in as it and revisit | Restricted controls are **absent**, not present-and-erroring |
+
+Then one explicit test per acceptance criterion: `PASS`, `FAIL`, or `NOT TESTABLE (reason)`.
+
+**Retry once before recording a failure**, using `browser_wait_for` on the element you expect rather than a fixed delay. A cold-start 502 on a Dev App Service is the most common false failure. If it passes on the retry, record `FLAKY`, not `PASS`.
+
+**Differential re-check.** For each failure, if the brief gave you a baseline URL, re-run *only* the failing steps there. Fails on the baseline too → the issue predates this story. Passes on the baseline → this story introduced it. Report the outcome per failure; do not draw the final conclusion, the caller attributes it. Cap at 5 re-checks and say if you hit the cap.
+
+## Write Safety
+
+You are operating on a shared environment with real integrations. A wrong click here sends real money or real email.
+
+- Prefer creating a new record over editing an existing one.
+- Prefix everything you create with `QA AB#<id>` so a human can find it.
+- **Never delete a pre-existing record.**
+- **Never** fire a bulk or destructive action, a payment submission or settlement, a batch approval, a 1099 or tax-document generation, an export-all, or anything that emails or notifies a real person.
+- If a screen can only be exercised by a destructive action, record `NOT TESTABLE — destructive` and move on.
+- List everything you created in the report.
+
+## Sensitive Data
+
+The project's `CLAUDE.md` forbids exposing TIN, SSN, EIN, TaxId, BankAccountNumber, RoutingNumber, and any `Encrypted*` variant — including encrypted values. On a real screen these are rendered, so:
+
+- **Never transcribe a field value** from a snapshot. Report only *present*, *populated*, *empty*, *masked*, or *validation shown*.
+- Prefer `browser_find` over a full `browser_snapshot` when you only need to check one element on a screen that displays protected fields.
+- **Never screenshot a screen showing a protected value.** Screenshots are failure evidence only, saved outside the repo, and referenced by local path — they are never attached to a work item.
+- If a screen exists to display protected data, test its structure, validation, and navigation, and record the content checks as `NOT TESTABLE — sensitive screen`.
+- If a tool result comes back blocked by the sensitive-data hook, do not retry it. Record `BLOCKED — protected fields on screen, manual QA required` and move to the next screen.
+
+## Report Format
+
+```markdown
+## QA — AB#{id}: {title}
+{type} · {state} · {environment} — {app-url}
+Signed in as: {role} (from {USERNAME_VAR}) — value not shown
+Screens tested: {n} · {route list}
+
+### Acceptance Criteria
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | {criterion} | PASS | {route} — {what you observed} |
+
+### Screen Regression — {route}
+| # | Test | Steps | Expected Result | Result |
+|---|------|-------|-----------------|--------|
+| 1 | Route loads | Navigate to {route} | Renders, no error boundary | PASS |
+
+### Failures
+#### F1 — {short title}
+- Screen: {route}
+- Steps: 1. … 2. … 3. …
+- Expected: {what should happen}
+- Actual: {what happened}
+- Evidence: console `{first line}` | network `POST /api/x → 500`
+- Differential: {passes on baseline | fails on baseline too | not checked — {reason}}
+- Touches this story's changed files: {yes — <file> | no}
+- Screenshot: {local path}
+
+### Not testable
+- {check} — {why}
+
+### Test data created
+- {entity} "QA AB#{id} — …" (id {x})
+
+**Sweep status:** COMPLETE | INCOMPLETE — {what was not reached}
+```
+
+## Rules
+
+- Never modify any file. Never post anything anywhere. Never ask the caller a question — report and stop.
+- Never change a work item state. You have no tool that can, and that is deliberate.
+- Never echo a credential value, and never include one in the report.
+- Never transcribe a protected field's value. See Sensitive Data.
+- A control you could not find is a **FAIL**, never a PASS. "I didn't see it" is not "it works."
+- If you run out of room and cannot finish the screens, report `INCOMPLETE` and name what you did not reach. A truncated sweep must never read as a pass.
+- Report what you observed, not what you expected the code to do. You are testing the deployed build, not the source.
+- Close the browser (`browser_close`) when you are done.

package/templates/commands/cherry-pick.md

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

package/templates/commands/create-release.md

@@ -60,7 +60,7 @@ Work items assigned:
 - AB#1235: Fix login redirect
 - AB#1236: View history
 
-Deploy it one environment at a time — each merge deploys, and the command advances the work items' states after you confirm the merge:
+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)