@chris1807/claude-kit 2.3.7 → 2.3.8

package/README.md

@@ -181,7 +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)
+├── qa.md                          # Browser QA + bug repro on a running environment (read-only)
 ├── build-validator.md             # Build checker (read-only)
 ├── lint-checker.md                # ESLint + dotnet format checker
 ├── azure-ops.md                   # Azure infrastructure management
@@ -698,7 +698,8 @@ Claude reviews for:
 | `/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 |
 | `/track` | `/track 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` |
+| `/qa` | `/qa AB#1234 [env] [--as=<user>]` | Verify the item is fully deployed with a green pipeline → open the app in a real browser → sign in (app login form, or Microsoft — you sign in once in the browser window) and optionally impersonate a user → full regression of the screens the story touched → pass/fail comment on the work item (never a state change). Environments: `local`, `dev`, `test`, `staging` |
+| `/repro` | `/repro AB#1234 [env] [--as=<user>] [--verify]` | Follow a bug's repro steps in a real browser. Before a fix: confirm it reproduces (with intermittency counts) and list the code to read. After the fix is deployed: prove it's gone, checked against a control run on a build without the fix. Mode is picked from where the fix commits are; posts a result comment (never a state change) |
 | `/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] [--next]` | Sweep the current sprint (or the next one with `--next`) 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 |
@@ -752,11 +753,14 @@ 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"
+# QA sign-in for /qa and /repro — OPTIONAL, per developer. Leave unset and you sign
+# in yourself in the browser window (recommended for your own admin account, since a
+# password the agent types lands in the local session transcript). The NAMES come
+# from your project's `## Environment URLs` section; _TEST / _DEV / _LOCAL / _STAGING
+# versions override the plain one on that environment.
+export COMPASS_QA_ADMIN_USERNAME="you@caresolutions.com"
 export COMPASS_QA_ADMIN_PASSWORD="..."
+export COMPASS_QA_ADMIN_PASSWORD_TEST="..."   # only if your test password differs
 
 # 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

@@ -692,6 +692,15 @@ async function main() {
       await fs.writeFile(gitignorePath, claudeBlock.trim());
       console.log(chalk.green('  ✓ Created .gitignore'));
     }
+
+    // Playwright MCP drops console logs and page snapshots into .playwright-mcp/ in
+    // the project root. /qa and /repro render real screens, so keep them out of git.
+    // Checked separately so installs that predate this line still pick it up.
+    const current = await fs.readFile(gitignorePath, 'utf8');
+    if (!/^\/?\.playwright-mcp\/?\s*$/m.test(current)) {
+      await fs.appendFile(gitignorePath, `${current.endsWith('\n') ? '' : '\n'}.playwright-mcp/\n`);
+      console.log(chalk.green('  ✓ Added .playwright-mcp/'));
+    }
   }
 
   // ── Install Manifest ──────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.3.7",
+  "version": "2.3.8",
   "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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Tests a work item in a real browser via Playwright MCP — a full regression of the screens a story touched, or a reproduce / verify-fix run of a bug's repro steps. Signs in with a test account (the app's login form, or a Microsoft session), can impersonate another user where the app supports it, 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
@@ -8,7 +8,15 @@ 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.
+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, and the main loop does any writing.
+
+You run one of three tasks, named in the brief:
+
+| Task | Caller | What you do |
+|---|---|---|
+| `regression` | `/qa` | Every row of the Regression Method on every screen given, plus one test per acceptance criterion |
+| `reproduce` | `/repro` | Follow a bug's repro steps and report whether the bug signature appears |
+| `verify-fix` | `/repro` | Follow the same steps on a build that contains the fix, and report whether the signature is gone and the expected behaviour is there |
 
 ## Tools you deliberately do not have
 
@@ -18,27 +26,72 @@ Do not work around these. If a check genuinely needs one, report the check as `N
 |---|---|
 | `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. |
+| `browser_file_upload`, `browser_drag`, `browser_drop` | Not needed by the methods 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.
+The caller passes a brief containing:
+
+- the **task**, plus the work item's id, title, type and state;
+- the target environment name, its App URL, and its API URL if known;
+- a **baseline** environment URL for differential re-checks or a control run, or `none`;
+- the **sign-in method** (`form` or `microsoft`), the sign-in descriptor, and the role;
+- whether the session was **handed over** (a person signed in by hand) or is **unattended** — and if unattended, the **names** of the environment variables holding the credentials;
+- if impersonating, the **impersonation descriptor** and the **target**, plus whether the target is a listed QA persona or an ad-hoc user;
+- for `regression`: the ordered list of screens with each screen's changed files, and the acceptance criteria;
+- for `reproduce` / `verify-fix`: the numbered steps, the **bug signature**, the **expected behaviour**, the number of attempts, and any **approved mutating steps**.
 
 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`.
+The brief says which of three cases applies.
+
+### Session handed over — either method
+
+A person has already signed in, by hand, in this same browser. They typed their own credentials, so you have none.
+
+1. `browser_navigate` to the App URL and confirm the signed-in marker from the descriptor. Stay in the tab you were given. A `form` app often keeps its session in `sessionStorage`, which a new tab doesn't share.
+2. **Never type into a login form or a Microsoft page.** On a `microsoft` app you may click the app's own sign-in button (e.g. "Sign in with Microsoft") **once per host**. That covers a baseline host nobody visited. If Microsoft completes silently and returns you to the app signed in, continue. If it shows anything at all, stop interacting with it: an account picker, an email or password field, an MFA prompt, "Stay signed in?". On a `form` app you cannot sign in anywhere else. Record every baseline re-check or control run as `not checked — session was handed over; no stored credentials`.
+3. If a sign-in screen or `login.microsoftonline.com` appears mid-run, stop right there. Report `BLOCKED — session ended at {route}` and list the screens and steps not reached. The caller has the person sign in again and resumes you with what's left.
+4. **Do not close the browser** when you finish. The caller closes it. Closing it would throw away a session a person typed in by hand.
+
+### Method `form` — unattended
+
+1. Read the credentials with Bash — `printenv <USERNAME_VAR>` and `printenv <PASSWORD_VAR>`, using the names the brief gives. They may be per-environment names like `…_PASSWORD_TEST`. 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`.
+4. If the app asks which role to sign in as, pick the role named in the brief. Missing from the list → `BLOCKED — account does not hold the {role} role`.
+5. 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. The account is often the developer's own, and a second failure risks locking them out.
+6. 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 redirected to an identity provider; the project's sign-in method should be microsoft, not form`.
 
-**Never** echo, log, repeat, screenshot, or include either credential value in your report. Never write one to a file.
+### Method `microsoft` — unattended
 
-## Regression Method
+The brief names credential variables for a cloud-only, MFA-exempt QA account.
+
+1. Read the credentials with `printenv` as above. Empty → `BLOCKED — <VAR> is not set`.
+2. Navigate to the App URL and click the app's sign-in button. On `login.microsoftonline.com`, type the username, then press "Next". Type the password, then press "Sign in". Each value is typed exactly once.
+3. At "Stay signed in?" choose "Yes", so the session survives into later batches.
+4. If you see any MFA or interactive prompt, stop: an authenticator, "Approve sign in request", "Verify your identity", "More information required", or a code entry. Report `BLOCKED — the account requires MFA; it cannot sign in unattended`. On "Your account or password is incorrect", stop and report `BLOCKED — sign-in failed`, and do not retry.
+5. Confirm the signed-in marker. If the sign-in page reappears mid-run, sign in once more the same way; a second loss is `BLOCKED — session ended at {route}`.
+
+**Never** echo, log, repeat, screenshot, or include a credential value in your report. Never write one to a file.
+
+### Impersonation
+
+When the brief names an impersonation target:
+
+1. Sign in first as the account the descriptor says can impersonate, in the role it requires.
+2. Follow the project's **impersonation descriptor** exactly: route, search box, row button, confirm dialog. Locate controls by the labels it gives. Scope a confirm click to the dialog, because a row button can carry the same name.
+3. **Exactly one row** must match the target. An exact username or email match beats a name match. If more than one row plausibly matches, report `BLOCKED — {n} users match "{term}"; narrow the search` and do not list the others. A locked row, a row with no impersonate button, or "no users match" is also `BLOCKED`, with the reason.
+4. If the brief names a role for the target and the row offers one button per role, use that role's button.
+5. Confirm you are now the target by the signal the descriptor gives, such as the landing route or a profile tooltip. In the report, name the target by the persona or the search term the caller gave. Never transcribe other fields from the results row.
+6. Impersonation can replace the session outright. To act as yourself again — for role gating, or a re-check on the baseline — end it the way the descriptor says, then sign in from scratch. That needs stored credentials. Under a handed-over session, stay as the target until the end, and record those checks as `not checked — session was handed over`. Impersonation is also environment-gated; if the baseline doesn't offer it, record the re-check as `not checked — impersonation unavailable on {baseline}`.
+7. **What you do while impersonating is recorded as the target user.** For a listed **QA persona**, Write Safety below applies unchanged. For an **ad-hoc user** — usually the person who reported a bug — you are **read-only**. You may navigate, open records, filter, sort, and open dialogs and cancel them. You never submit, save, approve, delete, upload, or send anything. The only exceptions are steps listed in the brief as **approved mutating steps**. A check that would need any other write is `NOT TESTABLE — would write as {target}`.
+
+## Regression Method — task `regression`
 
 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.
 
@@ -57,7 +110,7 @@ Work the screens in the order given. For each one, run **every** row of the chec
 | 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 |
+| 14 | Role gating | If the brief names a second role's credentials or a second impersonation persona, switch to it and revisit | Restricted controls are **absent**, not present-and-erroring |
 
 Then one explicit test per acceptance criterion: `PASS`, `FAIL`, or `NOT TESTABLE (reason)`.
 
@@ -65,6 +118,27 @@ Then one explicit test per acceptance criterion: `PASS`, `FAIL`, or `NOT TESTABL
 
 **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.
 
+## Reproduction Method — tasks `reproduce` and `verify-fix`
+
+You are given numbered steps and two definitions:
+
+- **Bug signature** — the observable that means the bug is present. Examples: `POST /api/payments → 500`, the total shows $0.00, a console `TypeError`, a Save button that stays disabled.
+- **Expected behaviour** — what a correct build does at the same point.
+
+1. **Run the steps exactly as written, in order.** Before each step, confirm its precondition with `browser_find` or `browser_snapshot`. Wait with `browser_wait_for` on the element you expect, never a fixed delay. Record what you observed at every step.
+2. **Look for the signature everywhere it can surface:** on screen, in `browser_console_messages`, and in `browser_network_requests`. Use the same evidence forms as Failures: the first console line, and `METHOD path → status`. If the bug is a protected value showing where it should be masked, the evidence is *"the field shows an unmasked value"* — never the value.
+3. **Classify each attempt as exactly one of:**
+   - `SIGNATURE SEEN` at step *n*;
+   - `NOT SEEN — expected behaviour observed`;
+   - `NOT SEEN — something else happened` (describe it);
+   - `STEP FAILED` at step *n* — the step could not be performed: a missing control, an unmet precondition, or a blocked screen.
+4. **Run the number of attempts the brief gives** (default 2). Start each one from a fresh navigation to the first step's route, and run them all even after an early sighting — `seen 1 of 3` is a real result for an intermittent bug, not noise. Take one screenshot at the first sighting, unless the screen shows a protected field.
+5. **`reproduce` only — variations.** If the signature was not seen in any attempt, try up to **3 variations** where the steps are ambiguous: a different record, a different filter value, or the other entry point to the same screen. Label them V1–V3 and say what changed. Never invent steps unrelated to the report. Variations obey every write rule.
+6. **`verify-fix` only — screen check.** After the attempts, run Regression Method rows 1–5 on the screen where the bug lived. That shows the fix didn't break the screen around it.
+7. **Control run.** If the brief asks for one, run the same steps on the baseline URL with the same sign-in and impersonation. Do one attempt, and a second if the first doesn't show the signature. Report `Control: SIGNATURE SEEN at step n | NOT SEEN | not run — {reason}`. The baseline is the build without the fix. The control is what tells "fixed" apart from "these steps never triggered it".
+
+Report what happened per attempt. **Do not assign the verdict** — the caller does, from your attempts plus the control.
+
 ## Write Safety
 
 You are operating on a shared environment with real integrations. A wrong click here sends real money or real email.
@@ -74,6 +148,8 @@ You are operating on a shared environment with real integrations. A wrong click
 - **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.
+- A repro step that would break one of these rules is `STEP FAILED — destructive`, even if the bug report says to do it. The caller decides whether a human runs it by hand.
+- While impersonating an ad-hoc user, the stricter read-only rule in Impersonation applies.
 - List everything you created in the report.
 
 ## Sensitive Data
@@ -88,10 +164,13 @@ The project's `CLAUDE.md` forbids exposing TIN, SSN, EIN, TaxId, BankAccountNumb
 
 ## Report Format
 
+### Task `regression`
+
 ```markdown
 ## QA — AB#{id}: {title}
 {type} · {state} · {environment} — {app-url}
-Signed in as: {role} (from {USERNAME_VAR}) — value not shown
+Signed in as: {role} ({form, from USERNAME_VAR | handed-over session | microsoft, from USERNAME_VAR}) — value not shown
+Impersonating: {persona | "search term"} as {role} | none
 Screens tested: {n} · {route list}
 
 ### Acceptance Criteria
@@ -124,13 +203,54 @@ Screens tested: {n} · {route list}
 **Sweep status:** COMPLETE | INCOMPLETE — {what was not reached}
 ```
 
+### Tasks `reproduce` and `verify-fix`
+
+```markdown
+## Repro — AB#{id}: {title}
+Task: {reproduce | verify-fix} · {environment} — {app-url}
+Signed in as: {role} ({method}) — value not shown
+Impersonating: {persona | "search term"} as {role} | none
+Bug signature: {as given}
+Expected behaviour: {as given}
+
+### Attempts
+| Attempt | Variation | Result | At step | Evidence |
+|---------|-----------|--------|---------|----------|
+| 1 | — | SIGNATURE SEEN | 4 | network `POST /api/x → 500` |
+| 2 | — | SIGNATURE SEEN | 4 | network `POST /api/x → 500` |
+| V1 | other record | NOT SEEN — expected behaviour observed | — | — |
+
+### Step log — attempt 1
+| # | Step | Observed |
+|---|------|----------|
+| 1 | {step} | {what happened} |
+
+### Screen check — {route}   ← verify-fix only
+| # | Test | Result |
+|---|------|--------|
+| 1 | Route loads | PASS |
+
+### Control run — {baseline-env}
+- {SIGNATURE SEEN at step n | NOT SEEN | not run — {reason}}
+
+### Not testable
+- {step or check} — {why}
+
+### Test data created
+- {entity} "QA AB#{id} — …" (id {x})
+
+Screenshot: {local path} | none
+**Run 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 echo a credential value, and never include one in the report. Never type into a login form or a Microsoft sign-in page unless the brief gave you credential variables.
 - 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.
+- While impersonating an ad-hoc user, never write. See Impersonation.
+- A control you could not find is a **FAIL**, never a PASS. "I didn't see it" is not "it works." In a repro, a step you could not perform is `STEP FAILED`, never `NOT SEEN`.
+- If you run out of room and cannot finish, report `INCOMPLETE` and name what you did not reach. A truncated sweep must never read as a pass, and a truncated repro must never read as "fixed".
 - 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.
+- Close the browser (`browser_close`) when you are done — **unless the session was handed over**, in which case leave it open for the caller. A Microsoft session survives closing, because the profile persists; an app session held in `sessionStorage` does not.

package/templates/commands/qa.md

@@ -1,10 +1,12 @@
-Regression-test a work item in a real browser against a running environment. Usage: `/qa <work-item-id> [environment] [--role=<role>] [--screens=/a,/b]`
+Regression-test a work item in a real browser against a running environment. Usage: `/qa <work-item-id> [environment] [--role=<role>] [--as=<persona-or-user>] [--as-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.
+- **`--as=<persona-or-user>`**: optional — after signing in, **impersonate** this user, using the app's own impersonation feature. A name from the project's persona table picks a QA test user. Anything else — an email, a username, or a name — is searched for literally, as an **ad-hoc user**. Requires an `**Impersonation:**` block in the project's `## Environment URLs`.
+- **`--as-role=<role>`**: optional — the role to impersonate a multi-role ad-hoc user as. A persona's role comes from its row.
+- **`--screens=/a,/b`**: optional — skip the affected-screen scoping in Step 6 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.
 
@@ -37,7 +39,7 @@ Read the **Environment URLs** table from the current repo's `CLAUDE.md`:
 | 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.
+Capture the target row's App URL and API URL, the `**Sign-in:**` descriptor, the test-account table, the `**Impersonation:**` block and its persona table if present, 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:
 
@@ -57,7 +59,8 @@ everything below that heading is replaced on the next kit update:
 | dev | Dev | https://… | {inferred, or …} |
 | test | Test | https://… | {inferred, or …} |
 
-**Sign-in:** form at `/login`. Signed-in landing: `/dashboard`.
+**Sign-in:** `form` at `/login`. Signed-in landing: `/dashboard`.
+  (or `microsoft` — Entra ID redirect; sign-in button "…". Signed-in marker: …)
 
 **Test accounts** — values live in environment variables; never write a password here.
 
@@ -91,40 +94,84 @@ so I can't open a browser. /qa cannot run.
  browser binaries may be missing — npx playwright install chromium}
 ```
 
-## Step 4: Gate — Credentials and Sign-in Method
+## Step 4: Gate — Sign-in Method, Credentials, Impersonation
 
-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:
+Read the **sign-in method** from the `**Sign-in:**` line, which starts with `` `form` `` or `` `microsoft` ``. An older descriptor may name neither. Treat it as `microsoft` only if it says sign-in **goes through** Microsoft, Entra ID, Azure AD, or MSAL. A line that says "no SSO, no MFA" is `form` — match the meaning, not the keywords. If the line is ambiguous, ask. Either way, say in the report that the descriptor should name its method.
+
+Resolve the role: `--role=<x>`, else the row marked `Default`, else the first row. With `--as`, 4c overrides this.
+
+### 4a. Method `form`
+
+Credentials are **per developer**. Each developer exports their own account's credentials on their own machine, under the variable names the table declares. The same person's account often has a different password on each environment, because test usually has its own database. So each variable resolves **per environment**: `{VAR}_{ENV}` first, then `{VAR}`. `{ENV}` is `LOCAL`, `DEV`, `TEST`, or `STAGING`. For example, `COMPASS_QA_ADMIN_PASSWORD_TEST` wins over `COMPASS_QA_ADMIN_PASSWORD` on test.
+
+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"
+  e="${v}_{ENV}"
+  if   [ -n "$(printenv "$e")" ]; then echo "$e SET"
+  elif [ -n "$(printenv "$v")" ]; then echo "$v SET"
+  else echo "$v MISSING"; fi
 done
 ```
 
-Any `MISSING`:
+Use `printenv`, not `${!v}`. Indirect expansion is bash-only and fails with `bad substitution` in zsh, the default macOS shell. The value is captured, never printed.
+
+Pass the agent the **resolved** names: whichever of each pair was `SET`.
+
+**Both set** → **unattended**: the agent signs in itself.
+
+**Either missing** → this is not an error. It means the developer hasn't stored credentials, so offer the **hand-off** instead:
 
 ```
 AB#{id}: {title}
 
-Missing test-account credentials for the {role} role:
-  - {PROJECT}_QA_ADMIN_PASSWORD
+No stored credentials for the {role} role on {environment}
+({PROJECT}_QA_ADMIN_USERNAME / {PROJECT}_QA_ADMIN_PASSWORD, or their _{ENV} versions).
 
-/qa signs in unattended, so these must be exported before it can run:
+  sign in → you sign in yourself, in the browser window Playwright opens, once the
+            plan is approved. Your password never passes through Claude.
+  stop    → set them first, for unattended runs:
+              export {PROJECT}_QA_ADMIN_USERNAME="you@example.com"
+              export {PROJECT}_QA_ADMIN_PASSWORD="…"
+              export {PROJECT}_QA_ADMIN_PASSWORD_TEST="…"   # if test differs
+            (add them to ~/.zshrc, then restart Claude Code)
 
-  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.
+Your own account is fine, as long as it holds the {role} role on {environment}. Never put
+a 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:
+**What a hand-off costs.** The session belongs to the person who signed in, in that one browser tab. The agent can't sign in anywhere else on its own. That rules out three things:
 
-```
-{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}.
-```
+- a differential re-check on the baseline — record `not checked — no stored credentials for {baseline}`;
+- a second role for checklist row 14 — record `NOT TESTABLE — one interactive session per run`;
+- returning to the admin account after impersonation ends — later screens run as the target user.
+
+Say all of this in the plan, so the developer can choose to set the variables instead.
+
+**Why offer it at all?** When the agent fills a login form, the password is a tool argument. It is stored in the session transcript on this machine and sent to the model, like every other tool call. For a throwaway QA account that is acceptable. For a developer's own **System Administrator** password it may not be. The hand-off is how a developer tests as themselves without that.
+
+### 4b. Method `microsoft`
+
+Two ways in. Pick by the role's row in the test-account table:
+
+- **The row names credential variables, and the `Sign-in:` line says the account is MFA-exempt** → **unattended**. Run the same per-environment presence check as 4a. The agent signs in on the Microsoft page itself.
+- **Otherwise** → **hand-off**. The person running `/qa` signs in once in the browser window Playwright opened. MFA is fine, and no credential enters any transcript. Nothing is checked here; the hand-off runs in Step 7a, after the plan is approved, so nobody signs in for a run they then cancel.
+
+Under `microsoft`, a hand-off costs less than under `form`. The session persists in the Playwright profile, and Microsoft often signs a second host in silently, so the baseline re-check usually still works. Role gating (checklist row 14) still needs a second sign-in, so it stays `NOT TESTABLE — one interactive session per run` unless `--as` supplies a second persona.
+
+### 4c. Impersonation — only when `--as` is given
+
+1. **The project must describe it.** No `**Impersonation:**` block in `## Environment URLs`:
+   ```
+   This project's CLAUDE.md doesn't describe an impersonation feature, so --as can't be used.
+   If the app has one, add an **Impersonation:** block to ## Environment URLs — the Claude Kit
+   Workflow section of CLAUDE.md shows the format.
+   ```
+2. **The environment must offer it.** The block lists where impersonation exists. If the target environment isn't listed, stop: `Impersonation isn't available on {environment} — the project lists {envs}. Run on one of those, or drop --as.`
+3. **Resolve the target.** If `--as` matches a persona name, case-insensitively, it is a **persona**: take the search term and role from the row. Anything else is an **ad-hoc user**: the value itself is the search term, and `--as-role` gives the role if one is needed.
+4. **The sign-in account is the one the block names as able to impersonate**, in the role it requires. That replaces `--role`; if both were given, say `--role` was ignored.
+5. **An ad-hoc user means a read-only run.** The app records everything done while impersonating as that user. So the agent submits nothing, and checklist rows 8–10 and 12, plus every criterion that needs a write, become `NOT TESTABLE — would write as {target}`. Say this in the plan. If the story *is* a write path, suggest a persona instead.
 
 ## Step 5: Gate — Is the Code Actually There?
 
@@ -217,7 +264,8 @@ Then present the plan and **wait**:
 
 Work item: {title} ({type}, {state})
 Target: {environment} — {app-url}
-Role: {role} ({USERNAME_VAR})
+Role: {role} ({USERNAME_VAR} | you'll sign in yourself in the browser window | Microsoft, unattended from {USERNAME_VAR})
+Impersonating: {persona} ({role}) | {search term} — ad-hoc user, READ-ONLY run | none
 Build: {n} of {n} commits on `{branch}`, {pipeline} run {id} green
 Baseline for attributing failures: {baseline-env} — {baseline-url}
 
@@ -238,7 +286,32 @@ 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.
+### 7a. Sign-in hand-off — whenever Step 4 chose a hand-off, for either method
+
+The agent can't ask anyone to sign in, so this step runs here, in the main loop, in the same browser the agent will use. Use only `browser_navigate`, `browser_find`, `browser_click`, and `browser_wait_for`. **Never type into a login form or a Microsoft page**, and never take a full snapshot of the landing page.
+
+First read the `playwright` entry's `args` in `.mcp.json`. With `--headless` there is no window to sign in through, so stop: `Signing in yourself needs a visible browser, but Playwright MCP is configured --headless. Remove the flag and restart the session.` With `--isolated` the hand-off still works, but a Microsoft session is gone at the end of every run. Say so once.
+
+1. `browser_navigate` to the App URL, then `browser_find` the signed-in marker from the `Sign-in:` line. **Found** → the browser still holds a session. Say `Reusing the session already in the Playwright browser. If that isn't a {role} account, say "switch" and I'll sign out first.`, then go to 7b.
+2. **Not found** → open the sign-in page. For `form`, that is the login route. For `microsoft`, click the app's sign-in button named in the descriptor and wait for `login.microsoftonline.com`. Then ask:
+   ```
+   Sign in to {environment} in the Chromium window Playwright opened, as an account
+   with the {role} role — your own is fine.{ If it asks which role, choose {role}.}
+   I don't see or type your credentials{, and MFA is fine}.
+
+   {microsoft: The session stays in the Playwright browser profile, so later /qa and
+    /repro runs skip this step until it expires.}
+   {form: The session lives in that browser tab — leave the window open until I'm done.}
+
+   Reply "done" when you can see the app.
+   ```
+3. On `done`, `browser_find` the marker again. Still missing → say which page the browser is on and ask once more. A second miss → stop. Microsoft error `AADSTS50011` means `{app-url}` isn't a registered redirect URI on the app registration. That is a configuration problem, not a test failure; say so and stop.
+
+### 7b. Delegate
+
+Delegate to the **qa** agent with a brief containing: task `regression`; the work item id, title, type and state; the target App and API URLs; the baseline App URL; the sign-in method and descriptor, with `session handed over` or `unattended`; the **names** of the credential variables (never the values — say "they are set, read them yourself, never echo them"); the impersonation block and target, marked persona or ad-hoc, if `--as` was given; 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.
+
+If the agent returns `BLOCKED — session ended`, run 7a once more and re-invoke it with only the screens it didn't reach. A second session loss → the report is `INCOMPLETE`. After a handed-over session, close the browser (`browser_close`) yourself once the last batch is done.
 
 When the report comes back, sort every failure using three filters, in order:
 
@@ -254,7 +327,8 @@ Only filter 1's output can drive a `FAIL` verdict. A run that finds nothing but
 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
+Signed in as: {role} ({from USERNAME_VAR | signed in by you | Microsoft, from USERNAME_VAR}) — value not shown
+Impersonating: {persona | search term} as {role} | none
 Screens tested: {n} · {route list}
 
 ## Acceptance Criteria
@@ -303,7 +377,7 @@ The body, as HTML (Azure DevOps renders HTML in comments):
 <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>
+Signed in as: {role} test account{, impersonating {persona | "an ad-hoc user (read-only run)"}}<br><br>
 
 <b>Acceptance criteria — {x} of {y} pass</b>
 <ul>

package/templates/commands/repro.md

@@ -0,0 +1,285 @@
+Reproduce a bug in a real browser — before a fix, to confirm it and pin it down, or after one, to prove it's gone. Usage: `/repro <work-item-id> [environment] [--verify | --reproduce] [--role=<role>] [--as=<persona-or-user>] [--as-role=<role>] [--attempts=<n>]`
+
+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`.
+- **`--verify` / `--reproduce`**: optional — force the mode. Without either, Step 3 picks it from where the fix is.
+- **`--role`, `--as`, `--as-role`**: exactly as in `/qa`. `--as` is how you reproduce a bug **as the user who reported it**, on an app that supports impersonation.
+- **`--attempts=<n>`**: optional — how many times to run the steps, 1–5. Defaults to 2, or 5 when an earlier `/repro` called the bug intermittent.
+
+**`prod` and `production` are refused**, for the same reason as `/qa`: an unattended run signs in and clicks through live member data. Say so and stop.
+
+`/repro` and `/qa` share one browser agent (**qa**) and one set of gates. `/qa` asks *"does this story work, and did it break anything?"* `/repro` asks a narrower question: *"does this bug happen?"* It asks it twice — once before the fix, so the developer starts from a confirmed reproduction, and once after, so "fixed" means something.
+
+## Step 1: Fetch the Bug
+
+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. Not found → report the error and stop.
+
+**Type gate.** Only a **Bug** or **Hot Fix** has repro steps. For any other type, stop:
+
+```
+AB#{id} is a {type}, which has no repro steps. /repro follows a bug's steps.
+To test a story's acceptance criteria, run /qa AB#{id} {environment}.
+```
+
+Capture: id, title, type, state, created by, linked Pull Request artifacts, and these fields:
+
+- `Microsoft.VSTS.TCM.ReproSteps` — the steps, usually followed by *actual* and *expected* results.
+- `Microsoft.VSTS.TCM.SystemInfo` — browser, environment, and account notes, when filled in.
+- `System.Description` — the fallback.
+
+Apply `/qa` Step 1's empty-field rules. `""`, whitespace, `<div></div>`, `<p><br></p>` and the `💡 Tip:` placeholder are all empty. Repro Steps empty → use the Description, and note `Repro steps read from Description`. Both empty → stop:
+
+```
+AB#{id} has no repro steps, so there's nothing to follow.
+
+Add them to the work item's Repro Steps and re-run — or give them to me here and I'll
+use them for this run only (they won't be written back to the work item).
+```
+
+**Read the comments.** Look for two things:
+
+1. **Earlier `/repro` results.** They start with `Automated repro —`. Record each one's mode, verdict, environment, commit, and date. A prior `REPRODUCED` can serve as the control in Step 3, and a prior `INTERMITTENT` raises the default attempts to 5.
+2. **Detail the steps leave out.** Which user hit it, which record, which environment, which browser. A named user feeds the `--as` suggestion in Step 4.
+
+Download and view every embedded `<img>` in the steps, description, and comments with WebFetch. A screenshot of the bug is often the clearest statement of its signature.
+
+## Step 2: Environment, Browser, Sign-in
+
+Read `.claude/commands/qa.md` and run its **Step 2** (Resolve the Environment), **Step 3** (Is a Browser Available?) and **Step 4** (Sign-in Method, Credentials, Impersonation) exactly as written. In their messages, say `/repro` where they say `/qa`. Every stop condition in those steps stops `/repro` too. One refinement applies: under an ad-hoc `--as`, `/qa` makes the whole run read-only, but `/repro` lets the user approve individual writing steps in Step 4.
+
+## Step 3: Pick the Mode
+
+Find the fix's commits the way `/qa` Step 5a does: linked PRs → `lastMergeCommit`; `git log --all --grep="AB#<id>\b" --grep="#<id>\b" -i --format=%H`; and branches matching `*AB#<id>-*`. Dedupe by SHA. Then check each commit against the target with `git merge-base --is-ancestor <sha> origin/<target-branch>`, or against `HEAD` for `local`.
+
+| Fix commits | On the target | Mode |
+|---|---|---|
+| none | — | **reproduce** — no fix exists yet |
+| some | not all | **reproduce** — the fix exists but isn't fully on {environment}, so this run confirms the bug on the old build |
+| some | all | **verify-fix** |
+
+For `local`, also count it as verify-fix when the current branch matches `*AB#<id>-*` and the working tree has uncommitted changes — that is a fix in progress. Remind the user that the running dev server must be serving this working tree.
+
+**Overrides.** `--reproduce` always wins. `--verify` on a target that lacks some fix commits is refused: verifying a fix that isn't deployed only tests the old build.
+
+```
+The fix for AB#{id} isn't fully on {environment} — {x} of {y} commits present.
+/repro --verify here would test the build without it.
+
+Run /repro AB#{id} {environment} to confirm the bug on this build, or verify where the
+fix is: {environments whose branch has every commit, or "nowhere yet"}.
+```
+
+**Verify-fix on `dev` / `test` / `staging`** → also run `/qa` **Step 5b**. The pipeline that deployed the fix must be green. Being merged is not being deployed. **`local`, either mode** → run `/qa` Step 5's `local` probe. Reproduce mode on a deployed environment needs no pipeline gate, because it tests whatever is there.
+
+**Pick the control** — verify-fix only. The control is what tells *fixed* apart from *these steps never triggered it*. Take the first one of these that applies:
+
+1. A prior `/repro` comment recorded `REPRODUCED` with the same steps, on a commit without the fix → it is the control. No control run is needed.
+2. Otherwise, walk down the `## Environment URLs` rows below the target, and take the first one whose branch lacks at least one fix commit. That environment still serves the bug. Under `--as`, it must also offer impersonation; skip any row that doesn't.
+3. Neither → no control. Step 6 can then only say `FIXED — UNCONFIRMED`, and the plan says so up front.
+
+## Step 4: Turn the Report Into a Script, Then Get Approval
+
+Rewrite the repro steps as a numbered script the agent can follow literally: a route, a control's visible label, the value to enter. Keep the report's own wording where it is already concrete. Resolve "go to the bills page" to the route. When a step names something vaguely, like *"a bill"* or *"any provider"*, keep it vague and let the agent pick a suitable record. Never invent a record id.
+
+Then define the two things the agent checks for. Without them a run proves nothing:
+
+- **Bug signature** — the *actual result*, made observable: a status code, a message, a wrong value, a console error, a control stuck in the wrong state.
+- **Expected behaviour** — the *expected result*: what a correct build shows at the same point.
+
+If the report doesn't say what the bug looks like, ask one question and wait: `What do you see when the bug happens? I need something observable — an error message, a wrong value, a failed request.`
+
+Mark every step that writes:
+
+- `← writes: {what}` — submits, saves, approves, or sends. It runs under the normal write rules: prefixed QA data, and nothing that emails a real person.
+- `← manual only — destructive` — it breaks one of the agent's write-safety rules: payment, settlement, bulk action, tax document, export-all, or a delete. The agent records it as `STEP FAILED`. If the bug sits behind such a step, say plainly that `/repro` can't reach it.
+- `← manual only — protected input` — it requires typing an SSN, TIN, bank account number, or another protected value. The agent never types one.
+- **Under an ad-hoc `--as`,** every writing step needs explicit approval here. Everything done while impersonating is recorded as that user. Approved steps go to the agent as **approved mutating steps**; the rest become `STEP FAILED — would write as {target}`.
+
+**Suggest impersonation when it fits.** Step 1 may have found a named user who hit the bug. If the project's `**Impersonation:**` block covers this environment and `--as` wasn't given, add `Tip: the report says this happens to {user} — re-run with --as="{user}" to reproduce it as them.` If the bug is about what a *role* sees, suggest the matching persona.
+
+Present the plan and **wait**:
+
+```
+## Repro plan — AB#{id} on {environment}
+
+Bug: {title} ({type}, {state})
+Mode: {reproduce — no fix exists yet
+       | reproduce — fix is on {branch} but not on {environment}
+       | verify-fix — {n} of {n} fix commits on `{branch}`, {pipeline} run {id} green}
+Target: {environment} — {app-url}
+Sign-in: {role} ({method})
+Impersonating: {persona} ({role}) | {search term} — ad-hoc user, read-only except approved steps | none
+Control: {baseline-env} — {url}, which doesn't have the fix
+        | prior /repro on {date} reproduced it on {env} at {sha7}
+        | none — {reason}; a pass can only be FIXED — UNCONFIRMED
+Attempts: {n}
+
+Steps:
+1. Go to /bills
+2. Open a bill in "Pending" status
+3. Click "Convert to Check"
+4. Click "Confirm" in the dialog          ← writes: converts the bill
+5. Open the Payments tab
+
+Bug signature: POST /api/bills/{ref}/convert → 500, and the error toast "Something went wrong"
+Expected behaviour: the bill shows status "Check Issued" and a payment row appears
+
+{Tip: …}
+
+Run it? (yes / edit the steps / edit the signature / cancel)
+```
+
+## Step 5: Run It
+
+If `/qa` Step 4 chose a hand-off, for either method, run `/qa` **Step 7a** (the sign-in hand-off) first.
+
+Delegate to the **qa** agent with a brief containing:
+
+- the task (`reproduce` or `verify-fix`), plus the bug's id, title, type and state;
+- the target App and API URLs;
+- the control's App URL, if the control is an environment, with "run a control" — otherwise `none`;
+- the sign-in method and descriptor, with `session handed over` or `unattended`;
+- the **names** of the credential variables, never the values;
+- the impersonation block and target, marked persona or ad-hoc, if `--as` was given;
+- the approved script, the bug signature, the expected behaviour, the approved mutating steps, and the number of attempts.
+
+If the agent returns `BLOCKED — session ended`, run `/qa` Step 7a once more and re-invoke it for the attempts it didn't reach. After a handed-over session, close the browser yourself at the end.
+
+**Under a `form` hand-off there is no control run on another environment.** The agent can't sign in there. Step 3's control then falls back to a prior `/repro` comment or none, and the plan must say so.
+
+## Step 6: Verdict
+
+Assign the verdict from the agent's attempts and the control. Count a `STEP FAILED` at or before the signature step as **not run**, never as *not seen*.
+
+### Reproduce mode
+
+| Attempts | Verdict |
+|---|---|
+| Signature seen in every attempt | `REPRODUCED` |
+| Seen in some attempts | `REPRODUCED — INTERMITTENT ({k} of {n})` |
+| Seen only under a variation | `REPRODUCED — under V{n}: {what changed}`. The report's steps are incomplete; recommend updating them |
+| Not seen, expected behaviour observed | `NOT REPRODUCED` |
+| Not seen, something else went wrong | `NOT REPRODUCED — DIFFERENT SYMPTOM: {what}` |
+| A step couldn't be performed | `BLOCKED — {reason}` |
+
+### Verify-fix mode
+
+| Target | Control | Verdict |
+|---|---|---|
+| Not seen in any attempt, expected behaviour observed, screen check clean | seen, or a prior `REPRODUCED` | `FIXED` |
+| Same | not seen, or no control | `FIXED — UNCONFIRMED` — the steps didn't trigger the bug on the old build either, so this run can't tell fixed from never-triggered |
+| Not seen, expected behaviour observed, screen check fails | any | `FIXED — SCREEN REGRESSION: {check}`. Attribute it the way `/qa` Step 7 does: does the failing surface touch the fix's changed files? |
+| Not seen, but expected behaviour **not** observed | any | `NOT FIXED — DIFFERENT SYMPTOM: {what happened instead}` |
+| Seen in any attempt | any | `STILL REPRODUCES ({k} of {n})` |
+| A step couldn't be performed | any | `BLOCKED — {reason}` |
+
+A verify-fix with fewer than 3 attempts on a bug a prior run called intermittent can only be `FIXED — UNCONFIRMED`. Two clean runs of a 1-in-3 bug is just luck.
+
+## Step 7: Where to Look — whenever the signature was seen
+
+The developer's next question is *where*. Answer it from the evidence, reading only:
+
+1. **Failing request → handler.** For each failing `METHOD path → status` the agent recorded, grep the API's controllers for the route attributes (`[Route]`, `[HttpPost("…")]`) that match. Report the action by `file:line`.
+2. **Screen → component.** Map the route where the signature appeared to its component through the client router, as `/qa` Step 6.3 does. Then look one hop down to the components that make the failing call.
+3. **Console error → source.** If the first console line names a function or a component, grep for it.
+
+Report at most 5 locations, each with the evidence that led there. **Never claim a root cause** — these are places to start reading.
+
+In **verify-fix** mode, when the bug still reproduces, run the same mapping. Then compare the locations with the fix commits' changed files. `the fix changed BillService.cs, but the failing call is handled in BillsController.cs:212` is the most useful sentence this command can produce.
+
+## Step 8: Report
+
+```
+Repro — AB#{id}: {title}
+{type} · {state} · {environment} — {app-url}
+Mode: {reproduce | verify-fix} · Build: {pipeline run {id}, commit {sha7} | local working tree}
+Signed in as: {role} ({method}) — value not shown
+Impersonating: {persona | search term} as {role} | none
+
+Verdict: {verdict}
+
+## Attempts
+| Attempt | Variation | Result | At step | Evidence |
+|---------|-----------|--------|---------|----------|
+| 1 | — | SIGNATURE SEEN | 4 | network `POST /api/bills/…/convert → 500` |
+| 2 | — | SIGNATURE SEEN | 4 | network `POST /api/bills/…/convert → 500` |
+
+## Control — {baseline-env | prior run {date}}
+{SIGNATURE SEEN at step n | NOT SEEN | not run — {reason}}
+
+## Screen check — {route}          ← verify-fix only
+{rows 1–5 from the agent}
+
+## Where to look                   ← when the bug reproduced
+1. `{file}:{line}` — {why: handles POST /api/bills/{ref}/convert, which returned 500}
+2. …
+
+## Not testable
+- {step or check} — {why}
+
+## Test data created on {environment}
+- {entity} "QA AB#{id} — …" (id {x}) — left in place for review
+
+Screenshot: {local path} — local only, not attached to the work item
+
+Next: {REPRODUCED → `/implement AB#{id}`
+       | NOT REPRODUCED → ask the reporter for the record, the user, and the environment
+         where it happened; or re-run with --as or in another environment
+       | FIXED → `Ready for Testing` / `Ready for Staging` is yours to set
+       | FIXED — UNCONFIRMED → reproduce it on the old build first: /repro AB#{id} {baseline-env} --reproduce
+       | STILL REPRODUCES / NOT FIXED → `/rework AB#{id}`, with the "Where to look" list above}
+```
+
+## Step 9: Comment on the Work Item
+
+Draft the comment, preview it, and **wait**, exactly as in `/qa` Step 9. Before drafting, check the existing comments for a `/repro` result with the **same mode and commit**. If one exists: `A /repro {mode} comment already exists for commit {sha7} ({date}). Post an updated one anyway? (yes / skip)`.
+
+This comment matters more than `/qa`'s, because the next `/repro` reads it. A `REPRODUCED` here becomes the control that lets a later verify-fix say `FIXED` rather than `FIXED — UNCONFIRMED`. So **always include the script and the signature** — they are what make two runs comparable.
+
+```html
+<b>Automated repro — {verdict}</b> · {mode} · {environment} · {date}<br>
+Build: {pipeline} run {id} · commit {sha7}{ | local working tree}<br>
+Signed in as: {role} test account{, impersonating {persona | "the reporting user"}}<br><br>
+
+<b>Steps run</b>
+<ol>
+  <li>{step}</li>
+</ol>
+<b>Bug signature:</b> {signature}<br>
+<b>Expected:</b> {expected behaviour}<br><br>
+
+<b>Result — signature seen in {k} of {n} attempts</b>
+<ul>
+  <li>Attempt 1: {result} at step {n} — {evidence}</li>
+</ul>
+{<b>Control</b> — {baseline-env}: {result}<br>}
+{<b>Where to look</b><ul><li><code>{file}:{line}</code> — {why}</li></ul>}
+{<b>Test data created</b><ul><li>{entity} "QA AB#{id} — …"</li></ul>}
+
+<hr>
+<i>Posted by <code>/repro</code>. Work item state unchanged. No screenshots and no field
+values are attached, per the sensitive-data policy.</i>
+```
+
+The comment never names an ad-hoc impersonation target. It says *"the reporting user"*, because the search term is often a real person's email.
+
+Then:
+
+```
+Repro 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. `/repro` never changes the work item's state — a `FIXED` doesn't move the bug forward, and a `NOT REPRODUCED` doesn't close it or tag it. Those are human calls. It 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/uat-reminder.sh

@@ -8,3 +8,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."
+echo "For a bug fix, /repro AB#<id> re-runs the repro steps and confirms the bug is gone."

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -18,7 +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
+  ├── qa → drives a real browser on a running environment: regression-tests a story's screens, reproduces a bug, verifies a fix
   ├── build-validator → confirms builds pass
   ├── lint-checker → runs ESLint and dotnet format
   ├── security-auditor → scans for secrets, vulnerabilities
@@ -83,7 +83,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) — **required by `/qa`** |
+| **Playwright** | Browser testing (navigate, click, fill, screenshot) — **required by `/qa` and `/repro`** |
 | **MongoDB** | Direct database queries and updates |
 | **Microsoft Teams** | Send/read team messages and notifications |
 | **Stripe** | Payment management (when configured) |
@@ -207,7 +207,7 @@ 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`.
+`/qa` and `/repro` are the exceptions that prove the rule: they test a work item in a browser and post a result comment, but they **never write a state** — not even `Ready for Testing`, and not even when `/repro` finds a bug `FIXED`.
 
 Human-only transitions — no slash command ever makes these: `Code Review → Ready for Testing` (the developer confirms the change on Dev), `Testing → Ready for Staging` (QA sign-off), `Staging → Ready to Deploy` (stakeholder / UAT sign-off), `Deployed → Closed` (verified in production).
 
@@ -395,7 +395,8 @@ All deployment and release operations are available as slash commands:
 | `/rollback` | `/rollback AB#1234 prod` | Revert commits on an environment |
 | `/track` | `/track 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) |
+| `/qa` | `/qa AB#1234 [env] [--as=<user>]` | Verify the item is fully deployed with a green pipeline → open the app in a real browser → sign in (app login form, or Microsoft) and optionally impersonate a user → full regression of the screens the story touched → pass/fail comment (never a state change) |
+| `/repro` | `/repro AB#1234 [env] [--as=<user>]` | Follow a bug's repro steps in a real browser. Before the fix: confirm it reproduces and point at the code to read. After the fix is deployed: prove the bug is gone, against a control run on a build without the fix → result 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] [--next]` | Sweep the current sprint (or the next one with `--next`) 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 (+ Investment Category / Impact where unset) + 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 |
@@ -467,7 +468,7 @@ Glasswing and Monarch (not yet migrated — 1 environment):
 
 ### 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.
+`/qa` and `/repro` open the app in a real browser. They need to know where each environment is hosted, how sign-in works, and which test account to use. Without this section they report and stop 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.
 
@@ -481,35 +482,92 @@ Add this to your project's `CLAUDE.md` — **above the `## Claude Kit Workflow`
 | 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`.
+**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.
+**Test accounts** — each developer sets the values on their own machine; 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` | |
+
+**Impersonation:** local, dev, test. Sign in as the `Admin` test account first.
+- Start: `/admin/impersonate` → type into "Search users" → "Search" → the row's "Impersonate" button → "Impersonate" in the confirm dialog.
+- You're the target when: the target's landing route loads.
+- End: "Logout" → `/login`. This ends the whole session; sign in again as the admin to continue.
+
+| Persona | Search term | Role | Notes |
+|---------|-------------|------|-------|
+| Provider | `qa-provider@example.com` | Provider | profile complete |
 ```
 
 **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.
+- **There is no `prod` row, deliberately.** `/qa` and `/repro` refuse production: an unattended run 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. That is how `/qa` tells a regression this story caused from a bug that was already there, and how `/repro` runs its *control*: it proves the steps still trigger the bug on a build without the fix, so a clean run on the fixed build means **fixed**, not *never triggered*.
 - **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.
+- **`Sign-in:`** starts with the method, then optional prose: the login route, the landing page, and an element that only exists once you're signed in.
+  - `` `form` `` — the app's own login form, with no MFA. If the developer has set the role's credential variables, the `qa` agent fills the form in itself. If not, the developer signs in by hand in the browser window — see Test accounts below.
+  - `` `microsoft` `` — Entra ID / MSAL redirect. Name the app's sign-in button and the signed-in marker. **By default the person running the command signs in by hand**, once, in the Chromium window Playwright opens. MFA is fine, and no credential enters any transcript. Playwright MCP keeps a persistent browser profile, so later runs reuse that session until it expires. For a fully unattended run, give the role's row credential variables **and** state on the `Sign-in:` line that the account is a cloud-only, **MFA-exempt** QA account. The agent then types them into the Microsoft page itself.
+  - A line naming neither method is read as `microsoft` only if it says sign-in goes through Microsoft / Entra ID, and as `form` otherwise. Name the method explicitly; that is less fragile than relying on this.
+- **Test accounts** are used by `/qa` and `/repro` and nothing else. The table declares the variable **names**. **Each developer sets the values on their own machine** — usually for their own account, which must hold the row's role on the environment being tested.
+  - **Per environment:** `{VAR}_{ENV}` overrides `{VAR}`, where `{ENV}` is `LOCAL`, `DEV`, `TEST`, or `STAGING`. Use it when your account's password differs on an environment with its own database — for example `COMPASS_QA_ADMIN_PASSWORD_TEST`.
+  - **Not set?** Then `/qa` and `/repro` don't stop. They offer to let you **sign in yourself** in the browser window, and your password never passes through Claude. The cost: the agent can't sign in anywhere else on its own, so on a `form` app there is no re-check on the baseline environment, and no second role.
+  - **Which to choose:** when the agent fills a form, the password is a tool argument. It is stored in the session transcript on your machine and sent to the model with every other tool call. For a dedicated QA account that's fine. **For your own administrator account, prefer signing in yourself.**
+  - The `Default` column marks the row 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. Under `microsoft` with a hand-off, the variable columns can be `—`; the role still says which account to sign in with.
+- **`Impersonation:`** is optional. Add it only if the app has a "sign in as another user" feature. It is what makes `--as=<user>` work, and it describes four things:
+  - **where** it's available — impersonation is often environment-gated;
+  - **which test account** can impersonate, and in which role;
+  - **how to start it**, using the visible labels of the controls;
+  - **how to end it** — say so if ending it signs you out completely.
+
+  The persona table names QA test users to impersonate by role. Use dedicated QA users, never a real person. `--as=<persona>` uses the row. Any other `--as` value is searched for literally, as an **ad-hoc user** — typically the person who reported a bug. The app records everything done while impersonating as that user, so an ad-hoc run is **read-only**: `/qa` submits nothing, and `/repro` asks you to approve each writing step.
+- **Never put a credential in these tables.** Only variable names. The values belong in your shell profile — see Environment Setup below.
 
-**Example from an actual project:**
+**Examples from actual projects:**
 
-COMPASS:
+COMPASS — `form` sign-in, plus impersonation:
 ```markdown
 | Branch | Environment | App URL | API URL |
 |--------|------------|---------|---------|
-| (none) | local | http://localhost:5173 | https://localhost:7169 |
+| (none) | local | http://localhost:3000 | http://localhost:5191 |
 | 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 |
+
+**Sign-in:** `form` at `/login` — app-issued JWT, no SSO, no MFA. If the account holds several roles, the login page asks which one; choose the table's role. Admin lands on `/admin/dashboard`.
+
+**Test accounts** — each developer uses **their own System Administrator account**, set on their own machine. Local and dev share a database; test has its own, so set `COMPASS_QA_ADMIN_PASSWORD_TEST` if your test password differs.
+
+| Role | Username variable | Password variable | Default |
+|------|-------------------|-------------------|---------|
+| System Administrator | `COMPASS_QA_ADMIN_USERNAME` | `COMPASS_QA_ADMIN_PASSWORD` | yes |
+
+**Impersonation:** local, dev, test — **not staging** (the API returns 404 there). Sign in as the `Admin` test account in the **System Administrator** role.
+- Start: `/admin/impersonate` → type into "Search users" → "Search" → on the row, "Impersonate" (or "Impersonate as <Role>" for a multi-role user) → "Impersonate" in the "Impersonate this user?" dialog.
+- You're the target when: the target's landing route loads. There is no impersonation banner.
+- End: "Logout" (drawer bottom row, or the avatar menu) → `/login`. This signs you out completely; sign in again as the admin to continue.
+- The token has no `impersonatedBy` claim — every action is recorded as the target.
+```
+
+CSIPay — `microsoft` sign-in, no impersonation:
+```markdown
+| Branch | Environment | App URL | API URL |
+|--------|------------|---------|---------|
+| (none) | local | http://localhost:3001 | https://localhost:5001/api |
+| dev | Dev | https://dev.csipay.caresolutions.com | https://dev.api.csipay.caresolutions.com/api |
+| test | Test | https://test.csipay.caresolutions.com | https://test.api.csipay.caresolutions.com/api |
+| staging | Staging | https://staging.csipay.caresolutions.com | https://staging.api.csipay.caresolutions.com/api |
+
+**Sign-in:** `microsoft` — Entra ID redirect via MSAL, single tenant. Any URL shows the "Sign in with Microsoft" button when signed out. Signed-in marker: the "Dashboard" heading at `/`. Roles are Entra app roles (`Admin`, `Developer`).
+
+| Role | Username variable | Password variable | Default |
+|------|-------------------|-------------------|---------|
+| Developer | — | — | yes |
+| Admin | — | — | |
+| User (no app role) | — | — | |
+
+Each developer signs in with their own Microsoft account. `Admin` and `Developer` see unmasked identifiers on Payees, which the sensitive-data hook blocks on sight. To test Payees content, sign in with an account that has no app role.
 ```
 
 ### Environment Setup
@@ -529,14 +587,16 @@ 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"
+# QA sign-in for /qa and /repro — OPTIONAL. Set these only if you want the agent
+# to sign in unattended. Leave them unset and you'll be asked to sign in yourself in
+# the browser window, so your password never passes through Claude.
+# The variable NAMES come from the project's `## Environment URLs` section. The
+# VALUES are yours — usually your own account with the role the table names — and
+# they live only here, never in any file. `_TEST` / `_DEV` / `_LOCAL` / `_STAGING`
+# versions override the plain one on that environment.
+export COMPASS_QA_ADMIN_USERNAME="you@caresolutions.com"
 export COMPASS_QA_ADMIN_PASSWORD="..."
-export COMPASS_QA_PROVIDER_USERNAME="qa-provider@example.com"
-export COMPASS_QA_PROVIDER_PASSWORD="..."
+export COMPASS_QA_ADMIN_PASSWORD_TEST="..."   # only if your test password differs
 ```
 
-`/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.
+When these are set, `/qa` and `/repro` read them **inside a subagent** and fill the login form directly. They never print a value, never write one to a file, and never include one in a report or a work item comment. The value is still a tool argument, so it lands in that subagent's local transcript. That is why signing in yourself is the better choice for a personal administrator account. Apps that sign in through Microsoft need no variables at all: you sign in once in the browser window, and the session persists in the Playwright profile.