@chris1807/claude-kit 2.1.55 → 2.1.57

package/templates/commands/qa.md

@@ -0,0 +1,353 @@
+Regression-test a work item in a real browser against a running environment. Usage: `/qa <work-item-id> [environment] [--role=<role>] [--screens=/a,/b]`
+
+Parse `$ARGUMENTS` to extract the work item ID. Accept formats like `AB#1234`, `#1234`, or just `1234`. If no ID is provided, report the error and stop.
+
+- **Environment**: optional — `local`, `dev`, `test`, or `staging`. Defaults to `dev`.
+- **`--role=<role>`**: optional — which test account to sign in as. Defaults to the row marked `Default` in the Environment URLs table, else the first row.
+- **`--screens=/a,/b`**: optional — skip the affected-screen scoping in Step 5 and test exactly these routes.
+
+**`prod` and `production` are refused.** An unattended regression pass signs in and clicks through live member data. Say so and stop.
+
+## Step 1: Fetch the Work Item
+
+Read the work item from Azure DevOps using the project from the current repo's CLAUDE.md configuration. Expand with `relations` so PR links are included.
+
+If the work item is not found, report the error and stop.
+
+Capture: id, title, type, state, and any linked Pull Request artifacts. Then extract the requirements **by type** — the field differs and getting this wrong silently produces an empty test plan:
+
+- **User Story / Feature** → `Microsoft.VSTS.Common.AcceptanceCriteria`.
+- **Bug / Hot Fix** → `Microsoft.VSTS.TCM.ReproSteps`. Neither type has an acceptance criteria field.
+
+Treat all of these as **empty**: `""`, whitespace, `<div></div>`, `<p><br></p>`, and the process-template placeholder `💡 Tip: Add "@serena rewrite" to Description for AI suggestions  Define acceptance criteria: - [ ]  - [ ]  - [ ]`. That last one is the trap — it is non-empty, so a length check says the opposite of the truth.
+
+If the type's field is empty, fall back to `System.Description` and note `AC read from Description — misfiled` in the report. If both are empty, **continue anyway** and report `Acceptance criteria: none — regression sweep only`. The screen sweep is the point of `/qa`; it does not need acceptance criteria.
+
+Download and view every embedded `<img>` in the description or criteria with WebFetch — mockups define the expected layout.
+
+## Step 2: Resolve the Environment
+
+Read the **Environment URLs** table from the current repo's `CLAUDE.md`:
+
+```
+| Branch | Environment | App URL | API URL |
+|--------|------------|---------|---------|
+| (none) | local | http://localhost:5173 | https://localhost:7001 |
+| dev | Dev | https://dev.myapp.example.com | https://dev.api.myapp.example.com |
+| test | Test | https://test.myapp.example.com | https://test.api.myapp.example.com |
+```
+
+Capture the target row's App URL and API URL, the `**Sign-in:**` descriptor, the test-account table, and — for the differential re-check in Step 7 — the **App URL of the row immediately below the target**. That row serves the pre-change build, which is what lets a failure be attributed rather than guessed at.
+
+If the section is missing, or the target environment has no row, report:
+
+```
+AB#{id}: {title}
+
+This project has no `## Environment URLs` section in CLAUDE.md, so I don't know where
+the {environment} app is hosted. /qa cannot run.
+
+Add this to CLAUDE.md — **above the `## Claude Kit Workflow` heading**, because
+everything below that heading is replaced on the next kit update:
+
+## Environment URLs
+
+| Branch | Environment | App URL | API URL |
+|--------|------------|---------|---------|
+| dev | Dev | https://… | {inferred, or …} |
+| test | Test | https://… | {inferred, or …} |
+
+**Sign-in:** form at `/login`. Signed-in landing: `/dashboard`.
+
+**Test accounts** — values live in environment variables; never write a password here.
+
+| Role | Username variable | Password variable | Default |
+|------|-------------------|-------------------|---------|
+| Admin | `{PROJECT}_QA_ADMIN_USERNAME` | `{PROJECT}_QA_ADMIN_PASSWORD` | yes |
+
+Want me to draft it with the API URLs filled in from your .env files? (yes / no)
+```
+
+The API URLs can be inferred from the client's per-environment env files (`Client/.env.development`, `.env.testing`, …), which already carry the API base URL. Grep for the single base-URL key and echo **only that value** — never print the contents of those files.
+
+For `dev`, `test`, and `staging` also read the **Pipeline Configuration** table; the two tables are joined on the branch column, and a mismatch is a configuration error worth reporting. If Pipeline Configuration is missing, report that the project has no pipeline configuration in `CLAUDE.md` and stop.
+
+## Step 3: Gate — Is a Browser Available?
+
+Two checks, both required:
+
+1. `.mcp.json` contains a `playwright` server. It is opt-in at install time, so a project that unchecked it has no browser.
+2. `mcp__playwright__browser_navigate` is present in this session's tools. The server can be configured and still have failed to start.
+
+```
+AB#{id}: {title}
+
+Playwright MCP isn't {configured for this project | connected in this session},
+so I can't open a browser. /qa cannot run.
+
+{To add it:  npx @chris1807/claude-kit init . --all --db=<your-db>  and check
+ "Playwright (browser testing)", then restart the session.}
+{It's in .mcp.json but didn't connect. Restart the session; if it still fails, the
+ browser binaries may be missing — npx playwright install chromium}
+```
+
+## Step 4: Gate — Credentials and Sign-in Method
+
+Resolve the role: `--role=<x>`, else the row marked `Default`, else the first row. Then check **presence only**. Never read a credential value in this step — the agent does that, inside its own transcript:
+
+```bash
+for v in {PROJECT}_QA_ADMIN_USERNAME {PROJECT}_QA_ADMIN_PASSWORD; do
+  [ -n "${!v}" ] && echo "$v SET" || echo "$v MISSING"
+done
+```
+
+Any `MISSING`:
+
+```
+AB#{id}: {title}
+
+Missing test-account credentials for the {role} role:
+  - {PROJECT}_QA_ADMIN_PASSWORD
+
+/qa signs in unattended, so these must be exported before it can run:
+
+  export {PROJECT}_QA_ADMIN_USERNAME="qa-admin@example.com"
+  export {PROJECT}_QA_ADMIN_PASSWORD="…"
+
+Use a throwaway QA account with least privilege, never a personal login. Never put
+the password in CLAUDE.md, .env, or any file in the repo.
+```
+
+If the `**Sign-in:**` descriptor says the app uses SSO or Entra ID with MFA, stop here:
+
+```
+{environment} sign-in goes through {provider} with MFA, which can't be completed
+unattended. /qa can't test this project until a cloud-only, MFA-exempt QA account
+exists — or run the checks by hand against {app-url}.
+```
+
+## Step 5: Gate — Is the Code Actually There?
+
+### For `dev`, `test`, `staging`
+
+Being merged is not being deployed. Two separate facts, both required.
+
+**5a. Every commit is on the branch.** Same method as `/where`:
+
+1. `git fetch origin <target-branch>` and `git fetch origin <baseline-branch>`.
+2. Find the item's commits three ways and dedupe by SHA: linked PRs → `lastMergeCommit`; `git log --all --grep="AB#<id>\b" --grep="#<id>\b" -i --format=%H`; branch names matching `*AB#<id>-*`.
+3. For each commit: `git merge-base --is-ancestor <commit> origin/<target-branch>`.
+
+**`/qa` requires all of them.** A partial match is the cherry-pick case `/where` reports as `1 of 2`, and testing half a story produces failures that are really missing code — a FAIL comment that blames a developer for a deployment mistake:
+
+```
+AB#{id}: {title}
+
+Not fully deployed to {environment} — 1 of 2 commits present.
+
+Present on origin/{branch}:
+  a1b2c3d  AB#{id}: add export button
+Missing:
+  e4f5g6h  AB#{id}: fix CSV encoding
+
+This is a partial cherry-pick. Get the rest onto {branch} (`/promote` or
+`/cherry-pick AB#{id} {environment}`), then re-run. `/where AB#{id}` shows the
+full picture.
+```
+
+No commits at all → `No commits found referencing this work item — nothing to test.` and stop.
+
+**5b. The pipeline that deployed them is green.** Same method as `/promote`:
+
+1. Take the merge time of the item's newest commit on the target branch.
+2. Look up the branch's pipeline ID(s) in Pipeline Configuration. Poll `pipelines_build` for runs on `refs/heads/<target-branch>` **queued at or after that time**, matching the merge commit where the run exposes it, and **capture each run's id**. A run that completed before the merge is not this deployment — never take "the latest run on the branch".
+3. Every pipeline on the branch (API **and** client) must be `succeeded`.
+4. **Never block on a foreground `sleep`.** If a run is still going, watch its **run id** with `Monitor` or Bash `run_in_background`, and match failures as well as success.
+
+| Result | Action |
+|---|---|
+| all `succeeded` | Proceed. Record `{pipeline} run {id}` for the report. |
+| `inProgress` | `The {environment} deployment is still running ({pipeline} run {id}). I'm watching it and will start testing when it's green. Say \`stop\` to cancel.` |
+| `partiallySucceeded` | `Not green — {stage} failed in run {id}. Test anyway? (proceed / hold)` and record it in the report. |
+| `failed` / `canceled` | Stop. `The {environment} deployment failed — run {id}, stage {stage}: {log link}. The app may not contain AB#{id} at all.` |
+| no run after the merge | Stop. `The commits are on {branch} but no CD run was queued after the merge. Nothing deployed AB#{id}.` |
+
+### For `local`
+
+No commit or pipeline gate — you are testing the working tree. Instead, probe the local App URL. If nothing answers:
+
+```
+Nothing is listening on {local-url}.
+
+/qa doesn't manage dev servers — start the app first:
+  {the project's start commands, e.g. `dotnet run --project src/API` and `npm run dev`}
+
+Then re-run /qa AB#{id} local.
+```
+
+Also check whether the working tree actually contains the item's commits (`git log --grep="AB#<id>"` on `HEAD`). If not, warn but continue — the user may be mid-implementation, which is a legitimate reason to run `/qa local`.
+
+## Step 6: Scope the Affected Screens, Then Get Approval
+
+Skip to the approval block if `--screens=` was given.
+
+1. **Changed files** — union of `git show --name-only --format= <sha>` over the item's commits, cross-checked against the linked PR's iteration changes. If they disagree, prefer the union and note it.
+2. **Partition** into frontend (`*.tsx`, `*.ts`, `*.css`, `*.scss` under the client project found via `Glob("**/package.json")`), backend (`*.cs`), and other.
+3. **Find the router** — `Glob("**/src/routes/**", "**/src/{App,Routes,router}.{tsx,ts}")`, then grep for `<Route`, `createBrowserRouter`, `path:`, `lazy(` to build a `{path → component file}` map.
+4. **Reverse-import walk, max 4 hops.** For each changed frontend file, grep the client `src/` for importers of its basename or path, and walk upward until you reach a file that is a router element. The union of reached routes is the candidate screen list. Keep the hop chain — it is the evidence for *why* a screen is in scope.
+5. **Backend endpoints → screens.** For each changed `*.cs` controller, read its route attributes (`[HttpGet("…")]`, `[Route("…")]`) to get endpoint paths, grep the client for each path to find the calling component, and feed those components back into step 4. This is what catches a backend-only story that still has a UI surface.
+6. **Name matching** — match nouns from the title and criteria against route paths and nav labels. Union in.
+7. **Confidence:**
+   - 1–6 routes reached by a clean import chain → proceed, and list them.
+   - More than 6 → present them all, test the 6 with the most changed files, say plainly that you are capping, and mention `--screens=`.
+   - **0 routes → stop and ask.** Never silently test nothing:
+     ```
+     I couldn't map the changed files to any screen. Changed: {n} frontend, {m} backend files.
+     {reason: no router found | only shared utilities changed | backend-only, no client caller found}
+
+     Which screens should I test?   /qa AB#{id} --screens=/payments,/invoices
+     ```
+
+Known blind spots, worth saying out loud in the report when they apply: computed `import()`, barrel-file re-exports that flatten the graph, and theme, design-token, or i18n changes that touch every screen. For a genuinely global change, say so and cap at the 4 highest-traffic routes rather than claiming to be exhaustive.
+
+Then present the plan and **wait**:
+
+```
+## QA plan — AB#{id} on {environment}
+
+Work item: {title} ({type}, {state})
+Target: {environment} — {app-url}
+Role: {role} ({USERNAME_VAR})
+Build: {n} of {n} commits on `{branch}`, {pipeline} run {id} green
+Baseline for attributing failures: {baseline-env} — {baseline-url}
+
+Screens the story touched:
+| Screen | Route | Why |
+|--------|-------|-----|
+| Payment History | /payments/history | PaymentHistory.tsx changed |
+| Export dialog | /payments/history | new component |
+| Payment detail | /payments/:id | calls the changed endpoint |
+
+Full regression of these {n} screens — every control, not just the new behaviour —
+plus {m} acceptance criteria, console errors, and failed network calls.
+
+This will create test data on {environment}, prefixed `QA AB#{id}`.
+
+Open the browser and run it? (yes / edit the screen list / cancel)
+```
+
+## Step 7: Run It, Then Attribute Every Failure
+
+Delegate to the **qa** agent with a brief containing: the work item id, title, type and state; the target App and API URLs; the baseline App URL; the sign-in descriptor; the **names** of the credential variables (never the values — say "they are set, read them yourself, never echo them"); the ordered screen list with each screen's changed files; and the criteria. Above 3 screens, invoke it once per batch so a long sweep can't exhaust its context mid-run.
+
+When the report comes back, sort every failure using three filters, in order:
+
+1. **Blame filter** — if the failing surface is not in the story's changed-file set and no changed file reaches it in the import walk, it is **pre-existing**. State the reasoning.
+2. **Differential result** — the agent re-ran failing steps against the baseline environment, which serves the pre-change build. Fails on both → **pre-existing**; passes on the baseline → **regression introduced by this story**, which is the strongest evidence a FAIL can carry. Caveat that seed-data and config drift between environments can confound this.
+3. **Flake filter** — the agent retried once. A pass on retry is `FLAKY`, not a failure.
+
+Only filter 1's output can drive a `FAIL` verdict. A run that finds nothing but pre-existing issues is `PASS WITH FINDINGS` — do not let old bugs turn into this story's failure.
+
+## Step 8: Report
+
+```
+QA — AB#{id}: {title}
+{type} · {state} · {environment} — {app-url}
+Build: {pipeline} run {id} · succeeded · commit {sha7}
+Signed in as: {role} (from {USERNAME_VAR}) — value not shown
+Screens tested: {n} · {route list}
+
+## Acceptance Criteria
+| # | Criterion | Result | Evidence |
+|---|-----------|--------|----------|
+| 1 | {criterion} | PASS | {route} — {observation} |
+| 2 | {criterion} | FAIL | see R1 |
+| 3 | {criterion} | NOT TESTABLE | {reason} |
+
+## Screen Regression — {route}
+| # | Test | Steps | Expected Result | Result |
+|---|------|-------|-----------------|--------|
+| 1 | Route loads | Navigate to {route} | Renders, no error boundary | PASS |
+
+## Regressions (attributable to AB#{id}) — {n}
+### R1 — {short title}
+- Screen: {route}
+- Steps: 1. … 2. … 3. …
+- Expected: {x}. Actual: {y}
+- Evidence: console `{line}` | network `POST /api/x → 500`
+- Differential: passes on {baseline-env} — introduced by this story
+- Screenshot: {local path} — local only, not attached to the work item
+
+## Pre-existing issues (found, not caused by AB#{id}) — {n}
+- {route} — {issue}. Also fails on {baseline-env}. Recommend a separate Bug.
+
+## Not testable — {n}
+- {check} — {why}
+
+## Test data created on {environment}
+- {entity} "QA AB#{id} — …" (id {x}) — left in place for review
+
+Verdict: PASS | PASS WITH FINDINGS | FAIL | INCOMPLETE
+Work item state unchanged — `Ready for Staging` is yours to set.
+```
+
+## Step 9: Comment on the Work Item
+
+Draft the comment, preview it, and **wait**. Before drafting, check the item's existing comments for a prior `/qa` result on the same commit SHA — three runs should not leave three near-identical comments. If one exists: `A /qa comment already exists for commit {sha7} ({date}). Post an updated one anyway? (yes / skip)`.
+
+> **Why this comment is not the redundant kind.** `/rework` deliberately posts no summary comment, because the commits and the diff are already the record of what changed. A QA result duplicates nothing: it is the outcome of *executing* the software at a specific build in a specific environment, which exists in no diff, no PR, and no pipeline log. It is precisely the evidence the person who later sets `Ready for Staging` needs. Don't delete this step by applying the `/rework` rule uniformly.
+
+The body, as HTML (Azure DevOps renders HTML in comments):
+
+```html
+<b>Automated QA — {verdict}</b> · {environment} · {date}<br>
+Build: {pipeline} run {id} ({result}) · commit {sha7}<br>
+Screens tested: {route list}<br>
+Signed in as: {role} test account<br><br>
+
+<b>Acceptance criteria — {x} of {y} pass</b>
+<ul>
+  <li>✅ {criterion}</li>
+  <li>❌ {criterion} — {one-line reason}</li>
+  <li>➖ {criterion} — not testable: {reason}</li>
+</ul>
+
+<b>Regressions introduced by this story ({n})</b>
+<ol>
+  <li><b>{title}</b> — {route}. Steps: {1-2-3}. Expected {x}, got {y}.
+      Passes on {baseline-env}, so it came in with this story.</li>
+</ol>
+
+<b>Pre-existing issues found ({n})</b> — not caused by this story; also fail on {baseline-env}.
+<ul><li>{route} — {issue}. Separate Bug recommended.</li></ul>
+
+<b>Test data created on {environment}</b>
+<ul><li>{entity} "QA AB#{id} — …"</li></ul>
+
+<hr>
+<i>Posted by <code>/qa</code>. Work item state unchanged — <b>Ready for Staging</b> remains
+a human QA gate. No screenshots and no field values are attached, per the sensitive-data
+policy.</i>
+```
+
+A `PASS` collapses to the header, the criteria list, the test-data list, and the footer.
+
+Then:
+
+```
+QA drafted — nothing has been posted to AB#{id} yet.
+
+## Work item comment
+{the full body as it will appear}
+
+Reply with one of:
+- "approve" → post the comment exactly as shown
+- "skip"    → post nothing (the report above is yours to keep)
+- "edit <section>: <new text>" → revise, then I'll re-preview before posting
+
+Wait for my response. Never post to the work item until I reply "approve".
+```
+
+On `approve`, post exactly one comment via `mcp__azure-devops__wit_work_item_comment_write`.
+
+That's it. `/qa` never changes the work item's state — not `Ready for Testing`, not `Ready for Staging`, not anything. `Ready for Staging` is the human QA gate and no command in this kit sets it. `/qa` also never merges, pushes, creates a PR, triggers a pipeline, edits code, attaches a screenshot to the work item, or transcribes a field value from a screen. It reads, it clicks, it reports.

package/templates/hooks/sensitive-data-output-blocker.sh

@@ -1,12 +1,29 @@
 #!/bin/bash
-# Sensitive Data Output Blocker Hook (PostToolUse - Bash, Read, Grep, MCP DB tools)
-# Scans tool output for sensitive PII field names that may have been returned
-# by broad database queries, file reads of seed/dump data, or grep results.
+# Sensitive Data Output Blocker Hook (PostToolUse - Bash, Read, Grep, Playwright, MCP DB tools)
+# Scans tool output for sensitive PII that may have been returned by broad database
+# queries, file reads of seed/dump data, grep results, or a rendered browser page.
 # Exit code 2 = BLOCK (prevents the output from being used).
+#
+# Two pattern sets, chosen by tool:
+#   * Database / file / grep tools -> match sensitive field NAMES. A query or a seed
+#     file that names TIN or SSN at all is already returning data it shouldn't.
+#   * Playwright (mcp__playwright__*) -> match a field name only when followed by
+#     something VALUE-shaped. A rendered screen legitimately shows "SSN:" as a form
+#     label, and blocking on the label alone would make every such screen untestable
+#     and send /qa into a retry loop.
 
 # Read the tool result from stdin
 INPUT=$(cat)
 
+# Extract the tool name so the pattern set can be chosen below
+TOOL=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('tool_name', ''))
+except:
+    pass
+" 2>/dev/null)
+
 # Extract output from any tool type (Bash stdout, Read content, Grep results, MCP results)
 OUTPUT=$(echo "$INPUT" | python3 -c "
 import sys, json
@@ -38,24 +55,45 @@ if [ -z "$OUTPUT" ]; then
     exit 0
 fi
 
-# Check if output contains sensitive field names as keys (indicating PII was returned)
-# These patterns match field names in JSON documents, MongoDB output, C# properties, etc.
-SENSITIVE_PATTERNS=(
-    # JSON/MongoDB style: "TIN": or 'TIN':
-    '"(TIN|Tin|TaxId|TaxIdentificationNumber|EIN|SSN|SocialSecurityNumber|EncryptedTin|EncryptedSSN|EncryptedTaxId|BankAccountNumber|AccountNumber|RoutingNumber)"\s*:'
-    # C# property style: .TIN = or .TaxId =
-    '\.(TIN|TaxId|TaxIdentificationNumber|EIN|SSN|SocialSecurityNumber|EncryptedTin|EncryptedSSN|EncryptedTaxId|BankAccountNumber|AccountNumber|RoutingNumber)\s*='
-    # YAML/config style: TIN: (start of line or after whitespace)
-    '(^|\s)(TIN|TaxId|TaxIdentificationNumber|EIN|SSN|SocialSecurityNumber|EncryptedTin|EncryptedSSN|EncryptedTaxId|BankAccountNumber|AccountNumber|RoutingNumber):\s'
-)
+FIELDS='TIN|Tin|TaxId|TaxIdentificationNumber|EIN|SSN|SocialSecurityNumber|EncryptedTin|EncryptedSSN|EncryptedTaxId|BankAccountNumber|AccountNumber|RoutingNumber'
+
+if [[ "$TOOL" == mcp__playwright__* ]]; then
+    # A rendered page: block only when a value actually accompanies the field name.
+    SENSITIVE_PATTERNS=(
+        # JSON body surfaced through the browser: "SSN": "123-45-6789"
+        "\"($FIELDS)\"\s*:\s*\"?[0-9]"
+        # Rendered value: SSN: 123-45-6789 / TIN = 12-3456789 / Account #: ****1234.
+        # Requires at least one real digit, so a fully masked "***-**-****" is allowed
+        # through -- that carries no data, and /qa needs to verify masking works.
+        "($FIELDS)\s*#?\s*[:=]\s*[\"']?[*Xx-]{0,8}[0-9][0-9*Xx-]{2,}"
+        # A bare SSN or EIN anywhere on the page, label or not
+        '\b[0-9]{3}-[0-9]{2}-[0-9]{4}\b'
+        '\b[0-9]{2}-[0-9]{7}\b'
+    )
+    BLOCK_MSG="BLOCKED: Browser output contains a sensitive value (SSN, TIN, bank account, etc.)"
+    BLOCK_HELP="Do not retry this snapshot. Record the screen as 'BLOCKED — protected fields on screen,
+manual QA required', test only its structure/validation/navigation, and move on.
+Never transcribe a protected field's value into a report or a work item comment."
+else
+    # Database / file / grep output: the field NAME appearing at all means PII was returned.
+    SENSITIVE_PATTERNS=(
+        # JSON/MongoDB style: "TIN": or 'TIN':
+        "\"($FIELDS)\"\s*:"
+        # C# property style: .TIN = or .TaxId =
+        "\.($FIELDS)\s*="
+        # YAML/config style: TIN: (start of line or after whitespace)
+        "(^|\s)($FIELDS):\s"
+    )
+    BLOCK_MSG="BLOCKED: Output contains sensitive PII fields (TIN, SSN, bank account, etc.)"
+    BLOCK_HELP="For database queries: use an explicit inclusion projection listing only non-sensitive fields.
+For code searches: avoid reading seed data, test fixtures, or dump files containing PII.
+If you need to work with this data, use the application UI instead."
+fi
 
 for PATTERN in "${SENSITIVE_PATTERNS[@]}"; do
     if echo "$OUTPUT" | grep -qE "$PATTERN"; then
-        echo "BLOCKED: Output contains sensitive PII fields (TIN, SSN, bank account, etc.)"
-        echo "The output includes documents or data with sensitive fields."
-        echo "For database queries: use an explicit inclusion projection listing only non-sensitive fields."
-        echo "For code searches: avoid reading seed data, test fixtures, or dump files containing PII."
-        echo "If you need to work with this data, use the application UI instead."
+        echo "$BLOCK_MSG"
+        echo "$BLOCK_HELP"
         exit 2
     fi
 done

package/templates/hooks/uat-reminder.sh

@@ -7,3 +7,4 @@
 
 echo "Reminder: If you just completed a feature implementation, run UAT before marking it done."
 echo "Ask Claude to generate a UAT checklist from the work item's acceptance criteria."
+echo "Once it is merged and deployed, /qa AB#<id> runs an automated browser regression of the affected screens."

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -18,6 +18,7 @@ You (give task)
   ├── deployer → commits, pushes, triggers CD pipeline
   ├── db-admin → queries/fixes MongoDB data
   ├── test-runner → runs xUnit, Vitest, Playwright tests
+  ├── qa → drives a real browser on a deployed environment, regression-tests the affected screens
   ├── build-validator → confirms builds pass
   ├── lint-checker → runs ESLint and dotnet format
   ├── security-auditor → scans for secrets, vulnerabilities
@@ -79,7 +80,7 @@ These run automatically — no action needed:
 | Server | What It Does |
 |--------|-------------|
 | **Azure DevOps** *(core — drives every slash command)* | Work items, repos, pull requests, pipelines, wiki, test plans, advanced security |
-| **Playwright** | Browser testing (navigate, click, fill, screenshot) |
+| **Playwright** | Browser testing (navigate, click, fill, screenshot) — **required by `/qa`** |
 | **MongoDB** | Direct database queries and updates |
 | **Microsoft Teams** | Send/read team messages and notifications |
 | **Stripe** | Payment management (when configured) |
@@ -100,10 +101,11 @@ Claude maintains persistent memory across sessions in `~/.claude/projects/.../me
 3. **Hooks guard** against secrets and bad patterns automatically
 4. **PR merges** into `main` — the compare branch. **Nothing deploys yet.** The work item stays in `Code Review` until it is promoted
 5. **Promote or release** — `/promote main dev` carries everything on `main` to Dev; `/create-release <N>` groups work items so `/deploy-release <N> test` → `staging` → `prod` can carry just those
-6. **Merge each promotion PR** — that merge is what triggers the environment's CD pipeline. Reply `merged` and the command advances the work items to `Testing`, `Staging`, or `Deployed`
-7. **Test** using Playwright MCP for browser testing
-8. **Track** work items via the Azure DevOps MCP server
-9. **Learn** — Claude saves what worked for next time
+6. **Say who verifies** — before the merge, the command asks who each product group (`COM`, `PAY`, …) should be assigned to in the target environment, offering the non-developer names already on those work items
+7. **Merge each promotion PR** — that merge triggers the environment's CD pipeline. The command watches it and, once it's green, sets the work items to `Testing`, `Staging`, or `Deployed` **and** assigns them to the approved verifiers — automatically, no reply needed
+8. **Test** using Playwright MCP for browser testing
+9. **Track** work items via the Azure DevOps MCP server
+10. **Learn** — Claude saves what worked for next time
 
 ### Story Points & Dev Ready Policy
 
@@ -159,7 +161,7 @@ feature/AB#1234-...  ──PR──▸  main  ──PR──▸  dev  ──PR
 
 #### Work Item States ↔ Environments
 
-Every environment in the chain has a work item state, so the board shows where each story physically is. The **"Ready for …" states are human gates** — QA or stakeholders set them when something passes; the slash commands never do. The **environment states** (`Testing`, `Staging`, `Deployed`) are set by the promotion commands once the PR into that branch has merged.
+Every environment in the chain has a work item state, so the board shows where each story physically is. The **"Ready for …" states are human gates** — QA or stakeholders set them when something passes; the slash commands never do. The **environment states** (`Testing`, `Staging`, `Deployed`) are set by the promotion commands once the PR into that branch has merged and its CD pipeline has come back green.
 
 | Branch | Environment | Gate — items should already be in… | Set once the PR into this branch merges |
 |---|---|---|---|
@@ -169,14 +171,26 @@ Every environment in the chain has a work item state, so the board shows where e
 | `staging` | Staging | `Ready for Staging` | `Staging` |
 | `prod` | Production | `Ready to Deploy` | `Deployed` |
 
+`/qa` is the exception that proves the rule: it tests a work item in a browser and posts a pass/fail comment, but it **never writes a state** — not even `Ready for Testing`.
+
 Human-only transitions — no slash command ever makes these: `Testing → Ready for Staging` (QA sign-off), `Staging → Ready to Deploy` (stakeholder / UAT sign-off), `Deployed → Closed` (verified in production).
 
 How the commands use this table:
 
 - **Gate check before the PR.** `/deploy-release`, `/cherry-pick`, and `/promote` compare each carried work item's state against the gate for the target environment. Anything behind the gate (e.g. still `Testing` when deploying to `staging`) is flagged and the user decides whether to include it. Items *ahead* of the gate (e.g. already `Deployed` on a cherry-pick to `prod`) are reported and left alone.
-- **Advance after the merge, not before.** The commands can't see the PR merge, so they finish by asking you to reply `merged` once the PR has completed and the pipeline is green; only then do they write the new state — for every carried User Story, Bug, and Hot Fix, never a Feature or Task, and never backward. `/status` reports items whose state lags the branch their commits are on and offers to catch them up.
+- **Advance on a green pipeline, automatically.** `/promote`, `/cherry-pick`, and `/deploy-release` do not stop at the PR. They poll it until it is `completed`, then poll the target branch's CD pipeline until every run finishes. Only on `succeeded` do they write the new state — for every carried User Story, Bug, and Hot Fix, never a Feature or Task, and never backward. A failed or canceled run changes **nothing** and is reported with the log link. `/status` reports items whose state lags the branch their commits are on and offers to catch them up.
+- **Assign the verifier at the same time.** The state change hands the item to a person, so the same three commands ask **before the merge** who each group of items should go to, then apply the assignee alongside the state once the pipeline is green. See **Verifier Assignment** below.
 - **Never assume the state list.** Confirm with `mcp__azure-devops__wit_work_item` (`action: get_type`) on an unfamiliar project before writing a state name — a bad name is accepted silently by a query and rejected only at write time.
 
+#### Verifier Assignment
+
+Moving an item to `Testing`, `Staging`, or `Deployed` puts it on someone's plate, so `/promote`, `/cherry-pick`, and `/deploy-release` also change who owns it. The developer implemented it; from here on it belongs to whoever checks it in that environment.
+
+- **Grouped by product prefix.** Work item titles are `PREFIX - Title`, so the commands group the carried items by prefix (`COM`, `PAY`, `CDA`, …) and ask **one question per group**. A staging → prod deploy carrying 2 `COM` and 2 `PAY` items asks twice; answering with the same person both times is fine, and `all 1` gives the whole batch to one person.
+- **Candidates come from the work items, never from a directory.** For each group the commands read the items' own history — who set the gate state (`Ready for Staging` / `Ready to Deploy`, from `list_revisions`), who created the item, who commented on it, who last edited it — then subtract the developers (current assignee, PR author, commit authors). What's left are the non-developer names actually attached to that work, ranked with the sign-off setter first. No name is ever invented.
+- **Asked before the merge, applied after.** The question comes while the PR is still in review and requires an explicit `yes`; nothing is written until the CD pipeline reports success. Then state and `System.AssignedTo` are set in the same update, and the report shows `was → now` for both so a wrong assignment is one edit to undo.
+- **`Leave the current assignee alone`** is always an option — the commands never clear an assignee, and never touch a Feature's or a Task's assignee.
+
 #### Release Management
 
 Releases group work items together for coordinated deployment across environments. Releases are tracked in Azure DevOps as iterations (`Release #N`) and work items are tagged with `release-{N}`.
@@ -193,7 +207,7 @@ This creates a `Release #23` iteration, assigns the selected work items to it, a
 /deploy-release 23 staging
 /deploy-release 23 prod
 ```
-This finds all work items in Release #23, checks each one against the target environment's gate state, cherry-picks their commits into a release branch (`release/23-to-staging`), creates a PR targeting the environment branch, links all work items, and — once you reply `merged` — advances them to the environment's state (`Testing`, `Staging`, `Deployed`).
+This finds all work items in Release #23, checks each one against the target environment's gate state, cherry-picks their commits into a release branch (`release/23-to-staging`), creates a PR targeting the environment branch, links all work items, asks who verifies each product group, and — once the merge's CD pipeline comes back green — advances them to the environment's state (`Testing`, `Staging`, `Deployed`) and assigns them to those verifiers.
 
 **Selective deployment:** Since releases are deployed via cherry-pick, you can deploy a full release or a subset. If staging has 5 user stories but only 3 are `Ready to Deploy`, create a release with just those 3 and deploy it.
 
@@ -213,7 +227,7 @@ Cherry-pick specific work items to an environment without a formal release:
 ```
 /cherry-pick AB#1234 AB#1235 prod
 ```
-This finds commits for the specified work items, checks them against the target's gate state, cherry-picks them into a branch (`cherry-pick/<date>-to-<environment>`), creates a PR, and advances the work items once you confirm the merge.
+This finds commits for the specified work items, checks them against the target's gate state, cherry-picks them into a branch (`cherry-pick/<date>-to-<environment>`), creates a PR, asks who verifies each product group, and — once the merge's CD pipeline is green — advances and assigns the work items.
 
 #### Promoting Environments
 
@@ -223,7 +237,7 @@ Promote all code from one environment to the next:
 /promote staging prod
 /promote                      ← auto-detects source and target from current branch
 ```
-This creates a PR from the source branch to the target branch with a summary of all included commits and their work items, checks the work items against the target's gate state, and advances them once you confirm the merge. `main → dev` is the usual first hop after feature PRs merge.
+This creates a PR from the source branch to the target branch with a summary of all included commits and their work items, checks the work items against the target's gate state, asks who verifies each product group, and — once the merge's CD pipeline is green — advances and assigns them. `main → dev` is the usual first hop after feature PRs merge.
 
 #### Rollbacks
 
@@ -288,13 +302,14 @@ All deployment and release operations are available as slash commands:
 | `/resolve-feedback` | `/resolve-feedback 142` | Address unresolved PR comment threads, push fixes, reply + resolve threads |
 | `/deploy` | `/deploy "commit message"` | Commit, push, trigger pipeline (only on `dev`/`test`/`staging`/`prod` — never on `main`) |
 | `/create-release` | `/create-release 23` | Group work items into Release #23 |
-| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → cherry-pick release to environment → PR → advance states after merge |
+| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → cherry-pick release to environment → PR → ask who verifies → advance + assign on a green pipeline |
 | `/add-to-release` | `/add-to-release 24 AB#4599` | Add work items to existing release |
-| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → cherry-pick specific work items → PR → advance states after merge |
-| `/promote` | `/promote main dev` | Promote all code between environments (`main → dev → test → staging → prod`) → advance states after merge |
+| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → cherry-pick specific work items → PR → ask who verifies → advance + assign on a green pipeline |
+| `/promote` | `/promote main dev` | Promote all code between environments (`main → dev → test → staging → prod`) → ask who verifies → advance + assign on a green pipeline |
 | `/rollback` | `/rollback AB#1234 prod` | Revert commits on an environment |
 | `/status` | `/status release 24` | Check release, pipeline, environment, or work item status; flags work items whose state lags their environment |
 | `/where` | `/where AB#1234` | Show which environment branches contain a work item's commits |
+| `/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 (never a state change) |
 | `/plan-backlog` | `/plan-backlog [project]` | Sweep backlog for Dev Ready stories with points and no tasks → propose child tasks with hours |
 | `/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). Pointed items move to Dev Ready; stories that can't be quoted move back to **Design Review**, bugs that can't be quoted get a **`needs-info`** tag, so the next sweep skips them. Every run also audits the drop-out queue (tagged bugs **and** stories bounced to Design Review) and reports any whose creator answered but which nobody returned to the sweep — neither mechanism expires, so those are otherwise invisible forever |
@@ -364,6 +379,53 @@ Glasswing and Monarch (not yet migrated — 1 environment):
 | develop | Dev | CD - Development (28) |
 ```
 
+### Environment URLs
+
+`/qa` opens the app in a real browser, so it needs to know where each environment is hosted and which test account to sign in as. Without this section `/qa` reports and stops rather than guessing a hostname.
+
+Add this to your project's `CLAUDE.md` — **above the `## Claude Kit Workflow` heading.** Everything from that heading to the end of the file is replaced on each kit update, so configuration placed below it is lost.
+
+```markdown
+## Environment URLs
+
+| Branch | Environment | App URL | API URL |
+|--------|------------|---------|---------|
+| (none) | local | http://localhost:5173 | https://localhost:7001 |
+| dev | Dev | https://dev.myapp.example.com | https://dev.api.myapp.example.com |
+| test | Test | https://test.myapp.example.com | https://test.api.myapp.example.com |
+| staging | Staging | https://staging.myapp.example.com | https://staging.api.myapp.example.com |
+
+**Sign-in:** form at `/login` — app-issued JWT, no SSO. Signed-in landing: `/dashboard`.
+
+**Test accounts** — values live in environment variables; never write a password here.
+
+| Role | Username variable | Password variable | Default |
+|------|-------------------|-------------------|---------|
+| Admin | `MYAPP_QA_ADMIN_USERNAME` | `MYAPP_QA_ADMIN_PASSWORD` | yes |
+| Provider | `MYAPP_QA_PROVIDER_USERNAME` | `MYAPP_QA_PROVIDER_PASSWORD` | |
+```
+
+**Rules for slash commands:**
+- **Branch names must match the `## Pipeline Configuration` table** row for row. The two tables are joined on the branch column — `/qa` reads the URL here and the pipeline ID there. A mismatch is a configuration error worth reporting.
+- **There is no `prod` row, deliberately.** `/qa` refuses production: an unattended regression pass signs in and clicks through live member data.
+- **Include the rows below the one you test.** The row immediately below the target serves the pre-change build, which is how `/qa` tells a regression this story caused from a bug that was already there.
+- **App URL is required; API URL is optional** — it is used to attribute a failing network call to the backend rather than the screen.
+- **`Sign-in:`** is optional prose. Include it when the login route is not `/login`, when the landing page is not obvious, or — importantly — when sign-in goes through **SSO / Entra ID with MFA**. Say so, and `/qa` reports that it cannot sign in unattended instead of hanging on a browser prompt.
+- **Test accounts** are required by `/qa` and nothing else. The `Default` column marks the account used when `--role` is not given; if no row is marked, the first row wins. A second role lets `/qa` verify that restricted controls are correctly *absent* — a class of bug a manual checklist rarely catches.
+- **Never put a credential in this table.** Only variable names. The values belong in your shell profile — see Environment Setup below.
+
+**Example from an actual project:**
+
+COMPASS:
+```markdown
+| Branch | Environment | App URL | API URL |
+|--------|------------|---------|---------|
+| (none) | local | http://localhost:5173 | https://localhost:7169 |
+| dev | Dev | https://dev.compass.caresolutions.com | https://dev.api.compass.caresolutions.com |
+| test | Test | https://test.compass.caresolutions.com | https://test.api.compass.caresolutions.com |
+| staging | Staging | https://staging.compass.caresolutions.com | https://staging.api.compass.caresolutions.com |
+```
+
 ### Environment Setup
 
 Each team member needs to set their own environment variables (never commit these):
@@ -380,4 +442,15 @@ az login
 
 # Microsoft Teams MCP — no env vars needed. First invocation prints a
 # device code + URL to sign in via Microsoft Graph (OAuth device flow).
+
+# QA test accounts (required for /qa — browser testing on a deployed environment).
+# One pair per role. The variable NAMES are declared in the project's
+# `## Environment URLs` section; the VALUES live only here, never in any file.
+# Use throwaway QA accounts with least privilege, never a personal login.
+export COMPASS_QA_ADMIN_USERNAME="qa-admin@example.com"
+export COMPASS_QA_ADMIN_PASSWORD="..."
+export COMPASS_QA_PROVIDER_USERNAME="qa-provider@example.com"
+export COMPASS_QA_PROVIDER_PASSWORD="..."
 ```
+
+`/qa` reads these itself **inside a subagent** and fills the login form directly. It never prints a value, never writes one to a file, and never includes one in a report or a work item comment. If your app's sign-in requires MFA or SSO, unattended login is not possible — say so in the `Sign-in:` line of `## Environment URLs` and `/qa` will report that instead of hanging on a browser prompt.