The AI QE Workflow

A complete, battle-tested operating model for AI-driven quality engineering — the agent authors the tests, executes manual charters, triages CI, files defects, verifies fixes, and reports the week. Extracted from a production Playwright + Java suite. Genericized for yours.
Read the workflow Adopt it in a day
MIT licensed·7 commands·7 pillars·stdlib-only Python connectors
Plate A — Verdicts
PASS FAIL BLOCKED
Honesty over green: a false PASS is worse than an honest FAIL.
Chapter One
Getting started

Three levels, each strictly safer than the next. Don't skip to the end — the whole point of the design is that you don't have to trust it blindly to get value from it.
Observe only
See what the agent would do, without it doing anything. Nobody needs to approve anything here — every command below is read-only by construction.
```
/create <TICKET> --dry-run
/manual-test <TICKET> --cases-only
/verify <TICKET> --dry-run
```
Move up when the test-case design consistently reflects your product on 2–3 real tickets.
One ticket, real writes, you review everything
Let the agent write code and comments for real, but keep every action reversible — nothing below advances a ticket.
```
/create <TICKET>
/manual-test <TICKET>
/verify <TICKET> --no-close
```
Move up when you're reviewing out of habit, not because you expect to catch something.
Standing authorization, the full loop
/verify, /verify-bug, and /manual-test now advance tickets to Done on their own. Get every box in TODO.md Part A approved first.
```
/verify <TICKET>
/verify-bug <BUG>
/manual-test <TICKET>
```
Steady state — this is what the first two levels exist to earn.
Read the full guide The approval checklist
No GitHub access?
Some organizations firewall github.com. This page is served from the plain domain qa.io.vn — if you can read this, you can copy the block below into a terminal from the root of your test repository. It recreates the whole handbook and toolkit as local files, with no network access and nothing that touches GitHub. Click inside the box, select all, and copy — the button below does the same thing in one click where supported.
#!/usr/bin/env bash
# The AI QE Workflow -- copy-paste bootstrap installer
# Generated from https://qa.io.vn -- recreates the handbook + toolkit locally.
# No network access required. Safe to re-run (overwrites these exact files only).
set -e
TARGET="${1:-qa-io-vn-workflow}"
echo "Installing The AI QE Workflow into $TARGET ..."
mkdir -p "$TARGET"
cd "$TARGET"

cat > "README.md" <<'QA_IO_VN_EOF'
# QA.io.vn — The AI QE Workflow Handbook

**A complete, battle-tested operating model for AI-driven quality engineering** — extracted
from a production Playwright + Java regression suite where an AI agent authors the tests,
executes manual charters, triages CI, files defects, verifies fixes, and reports the week.
Genericized so you can adopt it in any project.

**📖 Read it as a website: [qa.io.vn](https://qa.io.vn)**

---

## How to read this handbook

1. **[`WORKFLOW.md`](WORKFLOW.md)** — start here: the whole lifecycle, the seven commands,
   the seven pillars, how the pieces share state, and (§6) a stack-adapter table if you're
   not on Java + Maven + JUnit.
2. **[`ADOPTION.md`](ADOPTION.md)** — when you want it in your own project: a
   checklist that stands up a working skeleton in about a day.
3. **[`rules/PROJECT-INSTRUCTIONS-TEMPLATE.md`](rules/PROJECT-INSTRUCTIONS-TEMPLATE.md)** —
   the rulebook your AI agent follows; instantiate its placeholders for your stack.
4. **[`commands/`](commands/)** — the seven operational specs, one per lifecycle stage;
   read `create.md` and `manual-test.md` first to get the house style.
5. **[`toolkit/`](toolkit/)** — the stdlib-only Python connectors the commands call
   (Jira REST, Teams cards, failure-registry triage, bug filing).

---

## What's in here

| Path | What it is |
|---|---|
| [`WORKFLOW.md`](WORKFLOW.md) | The end-to-end lifecycle: stages, gates, shared state, division of labor |
| [`ADOPTION.md`](ADOPTION.md) | Step-by-step checklist to stand this up in a new project |
| [`rules/PROJECT-INSTRUCTIONS-TEMPLATE.md`](rules/PROJECT-INSTRUCTIONS-TEMPLATE.md) | The agent rulebook template (`CLAUDE.md` equivalent) — the seven pillars, instantiated for Playwright + Java |
| [`commands/`](commands/) | Seven ready-to-adapt slash-command specs — the operational workflow |
| [`toolkit/`](toolkit/) | Stdlib-only Python connectors: Jira REST, Teams cards, failure-registry triage, bug filing |
| [`docs/`](docs/) | The [qa.io.vn](https://qa.io.vn) website (GitHub Pages) |

## The seven commands

| Command | Stage | Gate before the outward action |
|---|---|---|
| `/create <ticket>` | Author automated coverage from a dev ticket | Every new test green (3× for UI) |
| `/manual-test <ticket>` | Design + execute a manual charter live | Every case passes |
| `/verify <ticket…>` | Audit real coverage, fill gaps, close the ticket | N clean runs, reruns off |
| `/verify-bug <ticket>` | Re-run a bug's mapped test, auto-advance | Stable green of the mapped test |
| `/ci [x] [build]` | Triage the CI build, fix test bugs, write bug tickets | Local green; extended = 3× + full suite |
| `/bug` | File bug tickets into Jira | Interactive confirm — the one command that asks |
| `/report [window]` | Weekly plain-English report from the git diff | Counts must trace to the diff |

## The seven pillars

1. **Inspect before you assert** — selectors and contracts come from the live product, never guessed.
2. **Test at the lowest sufficient layer** — E2E only for what a browser alone can prove.
3. **Page Object discipline** — one page per class, constants not magic strings, fluent API.
4. **Deterministic waiting** — hardcoded sleeps forbidden; every wait names its condition.
5. **Tests own their data** — seed → assert → clean up; leave the environment as found.
6. **The stable-green gate** — nothing closes on one lucky pass; reruns-off, 3× by default.
7. **Honesty over green** — blocked is a legitimate verdict; a false PASS is worse than an honest FAIL.

## Quick start

```bash
git clone https://github.com/qa-io-vn/qa.io.vn.git
# then follow ADOPTION.md — a working skeleton takes about a day
```

## License

MIT — see [LICENSE](LICENSE).
QA_IO_VN_EOF

cat > "WORKFLOW.md" <<'QA_IO_VN_EOF'
# The AI QE Workflow — end-to-end operating model

This document is the map of the whole workflow: how a ticket becomes automated coverage, how
manual testing happens, how CI failures are triaged, how defects are filed and verified, and
how the week is reported — with an AI agent operating every stage through a slash command,
governed by one rulebook (`rules/PROJECT-INSTRUCTIONS-TEMPLATE.md`), and wired to your
tracker/chat/CI through small Python connectors (`toolkit/`).

It is extracted from a production Playwright + Java test repository where this workflow runs
daily; everything here is battle-tested, then genericized.

---

## 1. The lifecycle at a glance

```mermaid
flowchart LR
  T[Dev ticket] -->|/create| A[Automated tests authored\n+ tracking task opened]
  T -->|/manual-test| M[Manual charter\nexecuted live]
  A -->|green| R[(Regression suite\nruns in CI)]
  M -->|all cases pass| DONE1[Ticket advanced to Done]
  M -->|case fails| DEF[Defect described\non the ticket]
  R -->|build report| CI[/ci triage/]
  CI -->|test bug| FIX[Fix + 3x stability gate]
  CI -->|product bug| BUGS[bugs/bug-NNN.md]
  BUGS -->|/bug| J[Jira Bug in active sprint]
  J -->|dev fixes| VB[/verify-bug/]
  T -->|delivery check| V[/verify/]
  V -->|coverage gap| A
  V -->|stable green| DONE2[Ticket advanced to Done]
  VB -->|stable green| DONE2
  FIX --> R
  R -->|weekly| REP[/report/]
```

| Stage | Command | In | Out | Gate before the outward action |
|---|---|---|---|---|
| Author coverage | `/create <ticket>` | Dev ticket | Tests + linked tracking task | Task advances only when **every new test is green** |
| Manual test | `/manual-test <ticket>` | Ticket | Charter + execution record + ticket comment | Advance to Done only when **every case passes** |
| Delivery check | `/verify <ticket…>` | Ticket(s) | Coverage audit, missing tests, ticket closed | **N clean runs** (default 3, reruns off) |
| Bug re-check | `/verify-bug <ticket>` | Bug + `bugs/` store | Verdict to Jira + Teams, auto-advance | Stable green of the **mapped** test(s) |
| CI triage | `/ci [x] [build]` | CI failure report | Fixes, bug tickets, dashboard | Fix counts only when locally green; extended mode = 3× + full suite |
| File defects | `/bug` | `bugs/bug-NNN.md` | Jira Bugs in active sprint | **Interactive confirm** (the one command that asks) |
| Reporting | `/report [window]` | git history | One plain-English paragraph | Counts must trace to the diff; undercount when unsure |

Two properties make this a *workflow* rather than seven scripts:

- **Shared state.** The commands communicate through durable artifacts: the local bug store
  (`bugs/bug-NNN.md` with `source_test`/`jira_key` frontmatter), the recurrence registry
  (`ci/known-failures.json`), manual charters (`manual-tests/<KEY>.md`), evidence
  (`.claude/ci-report/`), and the tracker itself. `/ci` writes bugs, `/bug` files them,
  `/verify-bug` closes them, `/verify` and `/manual-test` read them for context.
- **Division of labor.** Each command states what it does *not* do: `/ci` never creates Jira
  issues; `/bug` never re-triages; `/verify-bug` assumes coverage, `/verify` audits it;
  `/manual-test` writes no test code; `/report` only reads git.

---

## 2. The seven rule pillars

Everything in the project rulebook reduces to seven enforceable pillars. Commands cite them;
reviewers check them.

1. **Inspect before you assert.** Selectors, field ids, endpoints, and schemas are read from
   the live product (browser MCP tools / curl) or the frontend source — never guessed from a
   similar page. Efficiency rules keep this cheap: reference file first, Page Objects and
   config second, bundled `browser_run_code` missions, `browser_wait_for` polling, snapshots
   last with limited depth.
2. **Test at the lowest sufficient layer.** API/DB tests for contracts, validation, and error
   paths; E2E only for what a browser alone can prove. Packages separate the layers. No
   duplicated coverage across layers.
3. **Page Object discipline.** POs extend `BasePage`, one page per class, `private static
   final` selectors, `public static final` domain constants, a step-annotation + log line on
   every public action, fluent returns, a real `visit()` via config URL keys, a real
   `isLoaded()`, table rows as records, no assertions inside POs.
4. **Deterministic waiting.** Hardcoded sleeps are forbidden. Every wait names the condition
   it waits for (spinner, mask, network idle, element, specific response).
5. **Tests own their data.** Seed → assert → clean up (`try/finally`, `@AfterEach`), prefix
   created data `AUTOTEST_`, never depend on a previous test's leftovers, leave the shared
   environment as found.
6. **The stable-green gate.** Nothing advances a ticket or counts as "fixed" on one lucky
   pass: default 3 consecutive headless runs with test reruns disabled, run in the
   background, judged from the runner's reports. Raising the rerun count to launder a flake
   is explicitly banned.
7. **Honesty over green.** Every command ends with an honesty rule: blocked is a legitimate
   verdict, symptom-patch vs cure must be admitted, a false Done/PASS is worse than an honest
   failure. Recurrence labels (`ci/known-failures.json`) are priors to re-confirm, never
   verdicts to hide behind (FIX-FIRST).

---

## 3. Stage details

### 3.1 `/create` — from dev ticket to automated coverage
Reads the ticket (`ci/jira.py get`), maps each acceptance criterion to the lowest sufficient
layer, opens a **linked tracking task** before writing code (the board shows work started),
inspects the live UI/API, authors Page Objects + tests under full conventions, verifies
locally (headless, background, reruns off, 3× for UI), and only when **every** new test is
green advances the tracking task for human review. Red or blocked → it stays in progress
with an honest comment.

### 3.2 `/manual-test` — human-style testing, executed by the agent
Distills the ticket into testable acceptance criteria, designs a **manual test charter**
(`manual-tests/<KEY>.md`: happy path, negative, boundary, persistence check; user-level
steps), executes every case against the live product via browser MCP tools (curl for API
criteria), records per-case **PASS/FAIL/BLOCKED** with screenshots, comments the result
sheet on the ticket, posts a chat card, and advances the ticket to Done **only on an
all-pass run**. Failures produce ready-to-lift defect blocks; a manual PASS is a
point-in-time check, so the summary recommends `/create` for regression protection.

### 3.3 `/verify` and `/verify-bug` — proof before closure
`/verify` answers "is this ticket genuinely delivered?": audits whether existing automation
*actually asserts the ticket's expected result* (a stale `Class#method` mapping or a
nearby-but-different assertion counts as **no coverage**), authors what's missing, then runs
everything through the stability gate and closes the ticket with evidence. `/verify-bug` is
the narrow version for bugs with an already-mapped test: re-run it 3×, and on stable green
auto-advance the bug to Done, update `bugs/bug-NNN.md`, and post the verdict. Manual
live-check is its fallback — and a manual "fixed" never auto-closes there.

### 3.4 `/ci` — recurrence-aware triage, FIX-FIRST
Pulls the failed build's report, then triages every failure **on its own merits first**,
with `ci/known-failures.json` as a prior: test bugs are always fixed (smallest correct
change, verified locally, hardened 3×); product bugs are re-confirmed with a cheap live
probe and written up as ISTQB-style tickets into `bugs/`, never filed to Jira from here;
env/flake failures are re-confirmed by trace signature. Extended mode (`/ci x`) adds a hard
3× gate and a full local suite run minus documented known-bug classes. Never commits,
pushes, or triggers CI.

### 3.5 `/bug` — the one interactive gate
Files un-logged `bugs/bug-NNN.md` into Jira (active sprint, "To Do", mapped priority),
idempotently via the `jira_key` write-back. Because creating issues is outward-facing and
hard to undo in bulk, this is the only command that previews and **asks for confirmation**
before writing.

### 3.6 `/report` — the honest weekly paragraph
Reconstructs the week from the **diff**, not commit messages: new test classes and their
displayed test cases, genuinely-new cases in modified classes (undercount when unsure),
stabilization work by feature. Output is one plain-English paragraph for your manager — no
jargon, counts traceable to the diff.

---

## 4. Shared conventions (the glue)

- **Flag vocabulary** (same meaning everywhere): `--dry-run` = do the real read-side work,
  write nothing, print what would be sent · `--no-jira` / `--no-teams` / `--no-close` ·
  `--runs N` where a stability gate exists.
- **Verdict enum:** `Fixed/Passed (stable green) | Still reproduces / Failed | Inconclusive |
  Flaky` — chat cards map to `fixed` (green) / `reproduces` (red) / `inconclusive` (amber).
- **Canonical tracker walk:** `python3 ci/jira.py advance <KEY> --path "In Progress>In
  Review>To Deploy>To Test>Done"` sliced to start after the current status; `advance` skips
  reached waypoints and stops cleanly at an unavailable hop — report where it landed.
  Discover your own workflow once with `python3 ci/jira.py transitions <KEY>`.
- **Standing authorization:** `/verify`, `/verify-bug`, and `/manual-test` advance tickets
  without asking — but only their green-gates unlock it. `/bug` always asks.
- **Evidence paths:** `.claude/ci-report/<KEY>-verify.png`, `<KEY>-manual*.png`,
  `<fullName>.txt/.png`, `failures.json`, `bug-tickets.md` (all gitignored).
- **Credentials:** gitignored `.claude/{jira,teams,jenkins}.env`; a missing key means "say
  so and stop", never invent or hardcode.

## 5. Integration layer

| Tool | Purpose | Key invocations |
|---|---|---|
| `toolkit/jira.py` | Jira REST client | `get KEY`, `search --jql`, `comment --body-file`, `attach --file`, `transitions`, `transition --to`, `advance --path`, `create`, `link` |
| `toolkit/teams.py` | Teams Adaptive Card | `--status fixed\|reproduces\|inconclusive --bug --system --title --summary --url [--dry-run]` |
| `toolkit/triage.py` | Build failures vs registry | `[--build N] [--update]`; exit 1 iff NEW failures |
| `toolkit/bug_log.py` | File `bugs/` into Jira | `log [ids\|--all] --dry-run` then `--yes` |

In an adopting project these live under `ci/` and are invoked as `python3 ci/<script>.py`.
They are stdlib-only Python 3; credentials come from gitignored `.claude/*.env` files (see
the `*.env.example` templates). They are tracker/chat/CI connectors, not test-runner
connectors — nothing here is Java-specific.

## 6. Stack adapter — reading the command specs on a non-Java stack

`commands/*.md` and the rulebook template are lifted from the reference implementation
(Java + Maven + JUnit 5 + Playwright-Java), so their bash snippets say `mvn test
-Dsurefire.rerunFailingTestsCount=0`, `mvn spotless:apply`, `mvn checkstyle:check`, and talk
about Page Objects extending a `BasePage`. **None of that is load-bearing** — it's the one
concrete stack the model was proven on. What's load-bearing is the *shape* each line plays;
substitute your stack's equivalent for the shape, not the literal command:

| Shape (load-bearing) | Reference (Java/Maven) | pytest | Jest / Playwright Test (JS-TS) |
|---|---|---|---|
| Run the affected test(s) headless, in the background, log to a file | `mvn test -Dtest=Class#method -Dheadless=true -q >log 2>&1 &` | `pytest -k test_name -q > log 2>&1 &` | `npx playwright test -g "name" > log 2>&1 &` |
| Disable automatic retries (a real gate needs a clean signal) | `-Dsurefire.rerunFailingTestsCount=0` | `-p no:rerunfailures` (or don't install a rerun plugin) | `--retries=0` |
| N consecutive clean runs before trusting green | loop the run above N times, grep each report | loop + parse `--junit-xml` | loop + parse the JSON/HTML reporter |
| Auto-format touched files | `mvn spotless:apply` | `black .` / `ruff format` | `prettier --write` |
| Static lint / unused-import check | `mvn checkstyle:check` | `ruff check` / `flake8` | `eslint` |
| One-page-one-class UI abstraction with typed accessors | Page Object extends `BasePage` | Page Object class / fixture | Page Object class / component model |
| The JDK/runtime version a build targets | `JAVA_HOME` → JDK 21 | the pinned Python version (`pyenv`/`.python-version`) | the pinned Node version (`.nvmrc`) |

Everything else — the phases, the flag vocabulary, the stable-green gate, the honesty
rules, the artifact paths, the tracker/chat integration — is stack-agnostic as written. When
you port a command spec (`ADOPTION.md` Step 5), only the rows above change.

## 7. Where to go next

- **Adopting this in your project:** read `ADOPTION.md` — a step-by-step checklist.
- **The rulebook the agent follows:** `rules/PROJECT-INSTRUCTIONS-TEMPLATE.md`.
- **The command specs:** `commands/*.md` — drop into `.claude/commands/` and adapt the
  placeholders.
QA_IO_VN_EOF

cat > "ADOPTION.md" <<'QA_IO_VN_EOF'
# Adopting the AI QE Workflow in a new project

A step-by-step checklist to stand up the whole workflow in a fresh test repository. Budget
roughly a day for a working skeleton; the rulebook then grows with the project.

## Step 0 — Prerequisites

- A test repository (the reference implementation is Playwright + Java + JUnit 5 + Maven,
  but the workflow itself is stack-agnostic — commands, gates, and artifacts port as-is).
- An AI coding agent that reads a project rulebook and supports slash commands
  (e.g. Claude Code with `CLAUDE.md` + `.claude/commands/`).
- Jira (or any tracker with a REST API), optionally Teams/Slack for notifications, and a CI
  server that publishes test reports.

## Step 1 — Write the project rulebook

Copy `rules/PROJECT-INSTRUCTIONS-TEMPLATE.md` to your repo root as `CLAUDE.md` (or your
agent's equivalent) and instantiate every placeholder:

- [ ] Project structure table (where tests, page objects, config, helpers live)
- [ ] System → base-class mapping (one test base per system under test)
- [ ] URL/credential config keys (never inline URLs or credentials)
- [ ] Wait strategy table for your UI framework's loading signals
- [ ] Selector policy (`data-testid` first; structural selectors forbidden)
- [ ] Test-layering table (what belongs at E2E vs API vs unit)
- [ ] Code skeletons (one Page Object, one test class, in your house style)

The seven pillars (see `WORKFLOW.md` §2) must survive instantiation unchanged — they are
what keeps agent output trustworthy.

## Step 2 — Stand up the connectors

- [ ] Copy `toolkit/` into your repo as `ci/`
- [ ] Copy `ci/jira.env.example` → `.claude/jira.env`, fill `JIRA_BASE`, `JIRA_EMAIL`,
      `JIRA_TOKEN`, `JIRA_PROJECT`; verify with `python3 ci/jira.py whoami`
- [ ] (Optional) Teams: create a "post to channel on webhook" workflow, put its URL in
      `.claude/teams.env`; verify with `python3 ci/teams.py --text "hello" --dry-run`
- [ ] Ensure `.claude/*.env` is gitignored **before** the first commit
- [ ] Add a CI fetcher for your server (the reference uses a small script that downloads a
      build's failure report to `.claude/ci-report/failures.json`)

## Step 3 — Map your tracker workflow once

```bash
python3 ci/jira.py transitions PROJ-123
```

Write the resulting status path (e.g. `In Progress>In Review>To Deploy>To Test>Done`) into
the command specs wherever the canonical advance path appears. `advance` walks it hop by
hop and stops cleanly when a transition isn't available — so an imperfect path degrades
gracefully.

## Step 4 — Create the token-saving reference

Create an `AI_PLAYWRIGHT_REF.md` (or equivalent) with: environment URLs, the stable login
selectors, and copy-paste login mission bundles for your systems. This is what lets the
agent inspect the live product cheaply instead of taking full-page snapshots. Keep real
credentials OUT of it if the repo is ever shared — point to config keys instead.

## Step 5 — Install the commands

- [ ] Copy `commands/*.md` into `.claude/commands/`
- [ ] Replace the placeholder vocabulary: `APP-A`/`APP-B` → your systems,
      `https://app-a.example.com` → your URLs, `PROJ` → your Jira project key,
      the example status pipeline → your Step-3 path
- [ ] Keep the gates and honesty rules verbatim — they are the workflow
- [ ] Decide your standing authorizations: the reference lets `/verify`, `/verify-bug`, and
      `/manual-test` advance tickets without asking (only behind their green gates), while
      `/bug` always asks before creating issues. Adjust to your team's comfort.

## Step 6 — Start the shared state empty

- [ ] `bugs/` — created by `/ci`'s first product-bug write-up (gitignore it if bug content
      is sensitive)
- [ ] `ci/known-failures.json` — start `{"failures": {}}`; let `/ci --update` populate it.
      Never seed it with assumptions: a label that was never observed is a lie the workflow
      will repeat.
- [ ] `manual-tests/` — created by the first `/manual-test`

## Step 7 — Dry-run the loop end to end

1. `/create PROJ-123 --dry-run` — ticket read + test design printed, nothing written
2. `/manual-test PROJ-123 --cases-only` — charter designed, nothing executed
3. `/verify PROJ-123 --dry-run` — coverage audit + would-be actions printed
4. `/bug --dry-run` — sprint resolution + filing plan printed
5. Then run them for real on one small ticket and review every outward write (comments,
   transitions, cards) before trusting the standing authorizations.

## Anti-patterns to avoid

- **Seeding the registry from memory.** `known-failures.json` entries must come from
  observed builds; stale labels create the exact infinite loop the FIX-FIRST rule exists to
  break.
- **Weakening a gate to ship.** One green run, a rerun-masked flake, or a "probably fine"
  manual pass advancing a ticket — that is the failure mode this whole design defends
  against.
- **Letting the rulebook drift from reality.** When the product UI changes, update the
  rulebook and reference files in the same change as the test fix; contradictory docs make
  the agent guess, and guessing is what the workflow forbids.
QA_IO_VN_EOF

cat > "TODO.md" <<'QA_IO_VN_EOF'
# TODO — things a human should approve, and what's still open

Two different lists live here on purpose. The first is **governance**: decisions a lead or
team should explicitly sign off on before the agent runs unattended against a real tracker.
The second is **honest scope**: what this handbook doesn't cover yet. Pillar 7 is "honesty
over green" — that applies to this repository about itself, too.

## Part A — Approve before you enable standing authorization

`/verify`, `/verify-bug`, and `/manual-test` are designed to advance tickets and post
comments **without asking each time** — that's the point, it's what makes the loop
unattended. But "unattended" is a decision a team makes on purpose, not a default you fall
into. Before you drop the training wheels (`ADOPTION.md` Step 7), get an explicit yes on
each row below from whoever owns the tracker/CI/chat channel this will touch. Check a box
only once a real person has actually said yes — an unchecked box is a real gate, not
paperwork.

- [ ] **Auto-advance to Done.** `/verify` and `/verify-bug` transition tickets through your
      workflow to Done on a stable-green run, with no per-run confirmation. Approved by:
      _______________ Date: _______
- [ ] **Auto-advance on manual pass.** `/manual-test` advances a ticket to Done when every
      manual case passes, with no per-run confirmation. Approved by: _______________
      Date: _______
- [ ] **Jira comments and attachments.** Every command that touches Jira posts comments and
      uploads evidence (screenshots, logs) under the service account's identity. Confirm
      the account is one your team is comfortable posting as. Approved by: _______________
- [ ] **Chat notifications.** `/ci`, `/verify`, `/verify-bug`, and `/manual-test` post cards
      to a Teams/Slack channel. Confirm the channel and that the whole channel is fine
      receiving agent-authored posts. Approved by: _______________
- [ ] **The stable-green run count.** Default is 3 consecutive clean runs. If your suite is
      flaky enough that 3 isn't a meaningful bar yet, decide the real number *before*
      turning on auto-advance — raising it later to cover a bad week is the rerun-laundering
      anti-pattern this workflow explicitly forbids. Approved number: _____
- [ ] **Who `/bug` files into Jira, and where.** `/bug` still asks for confirmation every
      run (by design — see `WORKFLOW.md` §4), but confirm the target project, sprint, and
      priority mapping are correct before the first real use. Approved by: _______________
- [ ] **Credential scope.** The Jira/Teams/CI API tokens the toolkit uses should be scoped
      to what these commands actually need (comment, transition, attach, create issue in
      one project) — not a full-admin token. Confirm least-privilege scoping. Approved by:
      _______________
- [ ] **What `/ci` is allowed to change.** By default it edits test code and Page Objects to
      fix test bugs, but never commits, pushes, or triggers CI itself (`WORKFLOW.md` §3.4).
      Confirm your team is fine with an agent editing test files directly on a branch.
      Approved by: _______________

If any box above would get a "no" or "not yet" from its owner, run that command with
`--no-close` / `--dry-run` (every command supports one or both) until it's a yes. The
workflow is designed to be useful in observe-only mode — see `GETTING-STARTED.md` Level 1.

## Part B — Open items in this handbook (roadmap, not hidden gaps)

- **Tracker connector is Jira-only.** `toolkit/jira.py` speaks the Jira Cloud REST API.
  Linear, GitHub Issues, and Azure DevOps adapters don't exist yet — porting one means
  reimplementing `get/comment/attach/transitions/advance` against that tracker's API and
  keeping the same CLI shape so the command specs don't change.
- **Chat connector is a generic incoming-webhook card, described as "Teams."** It posts a
  single Adaptive Card shape; it isn't tested against Slack's Block Kit or Discord.
- **Reference stack is Java + Maven + JUnit 5 + Playwright-Java.** `WORKFLOW.md` §6 gives a
  translation table to pytest and Jest/Playwright-Test, but neither has been run end-to-end
  as a full port — treat it as a well-reasoned starting point, not a verified one.
- **No CI-server adapter beyond "download a failure report."** `/ci` assumes something
  produces a structured failure report (the reference used a Jenkins + Allure fetcher).
  GitHub Actions / GitLab CI / CircleCI equivalents aren't shipped.
- **Site is English-only, light-mode-only** (the editorial chapter design). No dark-mode
  media query, no i18n.
- **No worked example repository.** Everything here is templates and prose; there's no
  minimal sample project showing all seven commands running against a toy tracker.
  Volunteering one would be the single highest-leverage contribution.

Open a GitHub issue for any of the above, or — if your org can't reach github.com — see
`GETTING-STARTED.md`'s copy-paste path and raise it however your team already tracks
feedback that doesn't go through GitHub.
QA_IO_VN_EOF

cat > "LICENSE" <<'QA_IO_VN_EOF'
MIT License

Copyright (c) 2026 Tony

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
QA_IO_VN_EOF

mkdir -p "rules"
cat > "rules/PROJECT-INSTRUCTIONS-TEMPLATE.md" <<'QA_IO_VN_EOF'
# Playwright Automation Tests - AI Guide (Project Instructions Template)

> **What this file is**: the AI agent rulebook for your test-automation repository — the
> project instructions (`CLAUDE.md` or equivalent) that every AI coding session loads
> before touching the codebase. It encodes your conventions, guardrails, and workflow so
> the agent produces compliant code without re-litigating standards each session. Adapt
> the placeholders (APP-A / APP-B systems, `com.yourco.automation` packages, example URLs)
> to your own project, then keep the file checked into the repo root. This template is
> instantiated for the reference stack (Java + Maven + JUnit 5 + Playwright-Java) — its
> `mvn`/Surefire/spotless/checkstyle commands and Page-Object-in-Java conventions are one
> concrete implementation of the seven pillars, not a requirement of the workflow itself.
> On another stack, translate the commands (see `WORKFLOW.md` §6, "Stack adapter") and
> restate the coding-convention sections in your own language/framework's idiom — keep the
> *policy* each section encodes (inspect-before-assert, no magic values, deterministic
> waits, data ownership, fluent/composable page abstractions) even where the syntax changes.

## Playwright MCP — New Test Authoring (MANDATORY)

Before implementing any new Page Object or test class, **always use the Playwright MCP browser tools to inspect the live UI first**. This is required to ensure selectors, field IDs, tab names, and button labels are accurate and tests will pass without trial-and-error.

Minimum inspection steps for a new form/page:
1. Navigate to the target page via `browser_navigate`.
2. Use `browser_evaluate` to extract button labels, input IDs, and placeholder text from `[role='dialog']` or the page container — **do not guess from similar pages**.
3. Verify each tab's fields individually by clicking through tabs and re-running `browser_evaluate`.
4. Only then write the `*FormPage.java` and `*CrudTest.java` files using the confirmed selectors.

---

## Playwright MCP Efficiency Rules (CRITICAL)
To minimize token consumption and maximize speed, all AI interactions MUST follow these rules:

1. **Discover Before Acting**: Check `AI_PLAYWRIGHT_REF.md` first for stable selectors, URLs, and pre-defined mission bundles. If not found there, check the Page Object in `src/main/java/com/yourco/automation/ui/pages/[system]/` or `config/application.properties`. Never take a snapshot before checking these sources.
2. **Use `browser_run_code` for Missions**: Bundle multiple actions (navigation, filling forms, clicking) into a single JavaScript function. This avoids redundant snapshots and round-trips.
3. **Prefer `browser_evaluate`**: Use lightweight JS snippets to extract data or check states instead of taking a full DOM snapshot.
4. **Smart Waiting**: Use `browser_wait_for(text: "...")` for polling. It is significantly cheaper than taking multiple snapshots while waiting for a page state.
5. **Targeted Snapshots**: If a snapshot is absolutely necessary, use `depth: 3` to limit the payload size.

---

## Project Structure Quick Reference

| Layer | Location | Convention |
|---|---|---|
| Test Classes | `src/test/java/com/yourco/automation/[system]/[feature]/` | `*Test.java` |
| Page Objects | `src/main/java/com/yourco/automation/ui/pages/[system]/` | `*Page.java` |
| Base Framework | `src/main/java/com/yourco/automation/core/` | `BasePage`, `PlaywrightTestBase` |
| Test Bases | `src/test/java/com/yourco/automation/base/` | `AppATestBase`, `AppBTestBase`, etc. |
| Config | `config/application.properties` | Read via `ConfigManager.getInstance()` |
| Helpers | `src/test/java/com/yourco/automation/core/helpers/` | `*TestHelper` classes |

---

## AI QE Workflow — Command Catalog

The end-to-end lifecycle (ticket → coverage → CI triage → defects → verification → report)
is documented in `WORKFLOW.md` (repo root). Operating commands (specs in `.claude/commands/`):

| Command | Stage |
|---|---|
| `/create <ticket>` | Author automated coverage from a dev ticket (tracked by a linked AutoTask) |
| `/manual-test <ticket>` | Design + execute a manual test charter live, report verdict to Jira/Teams |
| `/verify <ticket…>` | Audit real coverage, author what's missing, stable-green gate, close ticket |
| `/verify-bug <ticket>` | Re-run a bug's mapped test; auto-advance to Done on stable green |
| `/ci [x] [build]` | Triage the Jenkins build, fix test bugs, write product-bug tickets |
| `/bug` | File `bugs/bug-NNN.md` into Jira (the one command that asks before writing) |
| `/report [window]` | Weekly plain-English report from the git diff |

*AutoTask is an issue type for tracking test work — substitute whatever your tracker uses.*

---

## Test Architecture Boundaries

Choose the correct test layer — never write E2E tests for things that belong at a lower level.

| Layer | When to use | Examples |
|---|---|---|
| E2E (Playwright) | Critical user flows and core regression only | Login flow, CRUD happy path, cross-module workflows |
| API/Integration | CRUD contracts, validation, error cases | REST endpoints, request/response schemas, error codes |
| Unit/Component | Rendering logic and local UI behavior | Computed values, form validators, isolated component states |

**Rules:**
- Default to API tests for backend validation — E2E should only cover what only E2E can cover.
- Do not duplicate API test coverage in E2E.
- Prefer API tests for negative/error cases; use E2E for the happy path.

---

## System → Base Class Mapping (MANDATORY)

**NEVER** extend `PlaywrightTestBase` directly in test classes. Always use the system-specific base (add one row per system under test — APP-A · APP-B · …):

| System | Test Base Class | Storage Key |
|---|---|---|
| APP-A | `com.yourco.automation.base.AppATestBase` | `"app-a"` |
| APP-B | `com.yourco.automation.base.AppBTestBase` | `"app-b"` |
| API Tests | `com.yourco.automation.core.BaseAPITest` | n/a |

---

## URL Property Keys (for `visit()` implementations)

Use these exact `ConfigManager` keys — never hardcode URLs:

| System | Key | Example Value |
|---|---|---|
| APP-A | `url.ui.app-a` | `https://app-a.example.com` |
| APP-B | `url.ui.app-b` | `https://app-b.example.com` |

---

## Credential Access (via ConfigManager)

Never inline credentials — always read them from your config/env files via `ConfigManager`:

```java
private final ConfigManager config = ConfigManager.getInstance();

// APP-A
config.getAppAUsername()   config.getAppAPassword()
// APP-B
config.getAppBUsername()   config.getAppBPassword()
```

---

## Session Management

- By default, all system-specific test bases restore the cached SSO session (e.g. Keycloak) from `StorageStateRegistry` — this skips the login page for speed.
- Login-flow tests MUST override `shouldApplyStorageState()` to force a real login:

```java
@Override
protected boolean shouldApplyStorageState() {
  return false; // Force real login — bypasses session cache
}
```

---

## Wait Strategy Reference (BasePage methods)

Use the correct `BasePage` wait for each scenario. **NEVER** use `page.waitForTimeout(ms)` — it is a hardcoded sleep and is forbidden. (Component-specific waits below assume a PrimeVue frontend — adapt the selectors to your UI library.)

| Trigger | Correct Wait | Notes |
|---|---|---|
| After a button click | `waitForSpinner()` | Waits for the UI library's progress spinner |
| After opening a modal | `waitForMask()` | Waits for the dialog mask/overlay (e.g. `.p-dialog-mask`) to appear |
| After page navigation | `waitForLoad()` | DOM content loaded |
| After data-heavy navigation | `waitForNetworkIdle()` | All XHR/Fetch requests complete |
| For an element to appear | `waitForElementToAppear(selector)` | Polls until visible |
| For an element to disappear | `waitForElementToDisappear(selector)` | Polls until hidden |
| For a specific CSS selector | `waitForSelector(selector)` | Raw selector wait |

---

## Dropdown Selection Decision Tree

Choose the correct `BasePage` method based on the UI component type (PrimeVue shown as the example — substitute your component library's class names):

| Component Type | HTML Pattern | BasePage Method |
|---|---|---|
| HTML native select | `<select>` element | `selectOption(selector, value)` |
| Styled dropdown | `.p-dropdown` class | `selectByText(dropdownSelector, optionText)` |
| Autocomplete | `.p-autocomplete` class | `selectAutoCompleteByText(inputSelector, optionText)` |
| Multi-select | `.p-multiselect` class | `selectMultipleAutoCompleteByText(inputSelector, List<String>)` |

---

## Coding Conventions

### 1. Code Style (Google Java Format)
- **Formatting**: Google Java Style: 2-space indent, K&R braces.
- **Imports**: Explicit only — no `.*` wildcards. Remove unused imports immediately.
- **Enforcement**: Always run `mvn spotless:apply` after creating or modifying any Java file.
- **No comments**: Do not add comments to code (Page Objects, tests, helpers). Well-named identifiers and Allure `@Step`/`@DisplayName` text carry the explanation. This applies to new code and edits alike — do not annotate a fix with a comment explaining what changed or why.

### 1. Clean Code & SOLID Principles (Core Rules)
- **Single Responsibility (SRP)**: Each Page Object must represent exactly ONE page or ONE logical component (e.g., `TransmitterFormPage` vs `EquipmentsPage`).
- **DRY (Don't Repeat Yourself)**: Extract common UI patterns (e.g., interacting with a specific table component type) into `BasePage` or a dedicated Component class.
- **KISS (Keep It Simple)**: E2E tests should verify the happy path and critical integration points. Avoid complex logic, loops, or conditional branching in test methods.
- **Naming**: 
  - Variables/Fields: Use descriptive names (e.g., `equipmentNameInput` instead of `input1`).
  - Methods: Use action-oriented names (e.g., `fillTransmitterDetails()` instead of `details()`).
- **Explicit Imports**: Never use wildcard (`.*`) imports. Remove unused imports immediately.
- **No Magic Strings**: All domain values, status codes, and environment keys MUST be constants or `ConfigManager` properties.

### 2. Maintainability Standards
- **Fluent API**: All public Page Object methods that perform an action MUST return `this` or the next logical Page Object. Never return `void`.
- **Try/Finally Cleanup**: Always use `try/finally` in tests that mutate state or open modals to ensure `cancel()` or `close()` is called in the `finally` block.
- **Local Variable Scope**: Declare Page Objects as local variables in `setUp()` or test methods unless used in multiple test methods within the class.
- **No Hardcoded Sleeps**: `page.waitForTimeout(ms)` is forbidden. Use `BasePage` wait methods (e.g., `waitForSpinner()`, `waitForElementToAppear()`).
- **No FQN in Code**: Avoid fully qualified names (e.g., `com.microsoft.playwright.Locator`). Use imports instead.

### 3. Page Object Model (POM) Rules
- All Page Objects MUST extend `BasePage` and be in `com.yourco.automation.ui.pages.[system]`.
- All selectors MUST be `private static final String SELECTOR_NAME = "..."`.
- Domain constants (status codes, mode names, action keys) MUST be `public static final String`.
- Every public method MUST have an Allure `@Step("Description")` annotation.
- Every public method MUST log with `logger.info(...)` or `logger.debug(...)` before the action.
- Return `this` (fluent) or the next logical Page Object. Never return `void` from action methods.
- No assertions inside Page Objects — assertions belong in test classes only.

### 3. Test Standards (JUnit 5)
- Use `assertTrue(condition, "Failure message")`. Message is ALWAYS required.
- Tag every test class with a system tag — `@Tag("APP-A")`, `@Tag("APP-B")`, or `@Tag("E2E")` (one tag per system under test).
- Test method names start with `test...` or `should...`.
- `@DisplayName` must be a plain English sentence — see DisplayName rules below.

---

## Test Authoring Rules (MANDATORY)

Non-compliance requires immediate correction without user prompting.

### 1. DisplayName — No Prefix Codes
- **NEVER** prefix `@DisplayName` with `AC1`, `AC2`, `TC1`, `TC2`, or any code.
- Bad:  `@DisplayName("AC1 - Mode dropdown appears after Add Step")`
- Good: `@DisplayName("Mode dropdown appears after Add Step")`

### 2. Navigation — Always Direct URL via `visit()`
- **NEVER** navigate by clicking through the Settings sidebar chain inside `@BeforeEach`.
- **ALWAYS** call `pageObject.visit()` which uses `page.navigate(url)` directly.
- `visit()` must use the `ConfigManager` property key for the base URL — never hardcode.

```java
@Override
public void visit() {
  String url = ConfigManager.getInstance().getProperty("url.ui.app-a") + "/settings/example-feature";
  navigateWithRetry(url, 3);
  clickFeatureTab(); // only if a tab click is needed after direct navigation
}
```

### 3. Constants — No Magic Strings for Domain Values
- Domain values used in `selectOption()` or assertions MUST be `public static final String` on the Page Object.
- Import with: `import static com.yourco.automation.ui.pages.appa.settings.FooPage.MODE_PARALLEL;`
- Bad:  `examplePage.selectStepMode(1, "PARALLEL");`
- Good: `examplePage.selectStepMode(1, MODE_PARALLEL);`

### 4. Test Class Fields — Declare Only What Is Used
- Declare a Page Object as a class field only if it is referenced in **more than one** test method.
- Page objects used only inside `setUp()` (e.g. `LoginPage`) MUST be **local variables** in that method.
- Remove unused imports immediately.

### 5. setUp() — Minimal and Fast
- `setUp()` must contain exactly: instantiate page objects → login → `pageObject.visit()`.
- **Do NOT call** `new DashboardPage(page).isLoaded()` after login — `login()` already guarantees dashboard readiness.
- **Do NOT call** navigation helpers that click through UI menus — put that logic in `visit()`.

### 6. Cleanup — Always Use `try/finally`
- Any test that opens a modal or mutates state MUST restore state in a `finally` block.

```java
@Test
@DisplayName("Adding a step opens the mode dropdown")
public void testAddingStepOpensModeDropdown() {
  try {
    examplePage.clickAddStep();
    assertTrue(examplePage.isModeDropdownVisible(), "Mode dropdown should appear after adding a step");
  } finally {
    examplePage.cancelAddStep();
  }
}
```

### 7. Page Object `visit()` and `isLoaded()` Contract
- Every Page Object MUST override `visit()` with a real `page.navigate(url)` call — empty bodies are forbidden.
- Every Page Object MUST override `isLoaded()` returning a boolean visibility check on a stable landmark element (e.g., a page heading or unique container).

### 8. Logging — Every Public PO Action Must Log
- Log at `logger.info` level before every user-facing action; `logger.debug` for intermediate steps.
- Use the `logger` field inherited from `BasePage` — never create a new logger in a Page Object.

```java
@Step("Select equipment type: {0}")
public EquipmentManagementPage selectEquipmentType(String type) {
  logger.info("Selecting equipment type: {}", type);
  selectByText(TYPE_DROPDOWN, type);
  waitForSpinner();
  return this;
}
```

### 9. Data Extraction — Use Java Records for Table Rows
- Page Objects that return table data MUST return typed records, not `List<Map<String, String>>`.

```java
// In the Page Object
public record EquipmentRecord(String id, String name, String type, String version, String status) {}

public List<EquipmentRecord> getEquipmentTable() { ... }
```

---

## Code Skeletons

### Page Object Skeleton

```java
package com.yourco.automation.ui.pages.appa.settings;

import com.yourco.automation.config.ConfigManager;
import com.yourco.automation.core.BasePage;
import com.microsoft.playwright.Page;
import io.qameta.allure.Step;
import java.util.List;

public class ExamplePage extends BasePage {

  // Stable landmark selector for isLoaded()
  private static final String PAGE_HEADING = "//h2[text()='Example Page']";

  // All UI selectors — private, static, final
  private static final String ACTION_BUTTON = "button.p-button[aria-label='Action']";
  private static final String STATUS_DROPDOWN = ".p-dropdown[data-testid='status']";

  // Domain constants — public, static, final; imported via static import in tests
  public static final String STATUS_ACTIVE = "ACTIVE";
  public static final String STATUS_INACTIVE = "INACTIVE";

  public ExamplePage(Page page) {
    super(page);
  }

  @Override
  public void visit() {
    String url = ConfigManager.getInstance().getProperty("url.ui.app-a") + "/settings/example";
    navigateWithRetry(url, 3);
  }

  @Override
  public boolean isLoaded() {
    return isVisible(PAGE_HEADING, 5000);
  }

  @Step("Click action button")
  public ExamplePage clickActionButton() {
    logger.info("Clicking action button");
    click(ACTION_BUTTON);
    waitForSpinner();
    return this;
  }

  @Step("Select status: {0}")
  public ExamplePage selectStatus(String status) {
    logger.info("Selecting status: {}", status);
    selectByText(STATUS_DROPDOWN, status);
    return this;
  }
}
```

### Test Class Skeleton

```java
package com.yourco.automation.appa.settings;

import static com.yourco.automation.ui.pages.appa.settings.ExamplePage.STATUS_ACTIVE;
import static org.junit.jupiter.api.Assertions.assertTrue;

import com.yourco.automation.base.AppATestBase;
import com.yourco.automation.config.ConfigManager;
import com.yourco.automation.ui.pages.appa.LoginPage;
import com.yourco.automation.ui.pages.appa.settings.ExamplePage;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;

@Tag("APP-A")
public class ExampleTest extends AppATestBase {

  // Declare only page objects used in more than one test method
  private ExamplePage examplePage;
  private final ConfigManager config = ConfigManager.getInstance();

  @BeforeEach
  public void setUp() {
    LoginPage loginPage = new LoginPage(page); // local var — only used here
    examplePage = new ExamplePage(page);
    loginPage.visit();
    loginPage.login(config.getAppAUsername(), config.getAppAPassword());
    examplePage.visit();
  }

  @Test
  @DisplayName("Action button processes the request successfully")
  public void testActionButtonProcessesRequestSuccessfully() {
    try {
      examplePage.clickActionButton();
      assertTrue(examplePage.isLoaded(), "Page should remain loaded after action");
    } finally {
      examplePage.cancelAction(); // restore state for next test
    }
  }

  @Test
  @DisplayName("Status dropdown filters the table to the selected status")
  public void testStatusDropdownFiltersTable() {
    examplePage.selectStatus(STATUS_ACTIVE);
    assertTrue(examplePage.isLoaded(), "Page should remain loaded after filter");
  }
}
```

---

## Implementation Workflow (MANDATORY)

For any UI or E2E task, follow this sequence:

1. **Inspect first**: Use MCP Playwright to verify live UI behavior before writing or changing tests when behavior is unclear.
2. **Implement incrementally**: Write tests in small, verifiable batches — not all at once.
3. **Run after each change**: After each meaningful change, run the affected tests and fix failures using runtime evidence, not guesswork.
4. **Verify impact**: Ensure new tests pass AND that impacted existing tests still pass.
5. **Prefer maintainability**: Choose patterns that are stable and readable over quick patches.

---

## Reliability & Maintenance (SOP)

- **Explicit Waits**: Always use the wait methods in the Wait Strategy Reference above.
- **No Hardcoded Data**: Use `ConfigManager` for all URLs, credentials, and environment values.
- **Exception Handling**: Throw a descriptive `RuntimeException` with context — never return `null` or `false` silently.
- **Stable Selectors**: Prefer `data-testid` attributes. Never use `:nth-child`, `:nth-of-type`, or index-based selectors — they break when DOM order changes.
- **Test Data Isolation**: Each test must own its data — set it up, assert, and clean up. Never rely on state left by a previous test.
- **Checkstyle**: Run `mvn checkstyle:check` to catch star imports, unused imports, and redundant imports.
- **Format**: Run `mvn spotless:apply` after every file change before committing.

## PR Review Roles (Automated AI Reviewer)

These 5 reviewer roles are evaluated automatically on every pull request (substitute your own AI PR-review bot):

| Role | Trigger | Checks |
|---|---|---|
| 🔒 Security | Always | Hardcoded secrets, SQL/shell injection, vulnerable new dependencies |
| 🧹 Code Quality | Always | POM compliance (`private static final` selectors, fluent API), DRY, naming |
| 🧪 Test Coverage | `src/main/` changes | New logic in main without a test, missing edge cases |
| ⚡ Performance | Any Java change | Unclosed `BrowserContext`/`Page`, expensive ops inside loops, blocking threads |
| 📡 API Contract | `api/`, `config/`, `pom.xml` | Renamed/removed fields, hardcoded base URLs, wrong HTTP verbs |

Every finding must include a concrete remediation step. If no issues are found, the reviewer confirms with a "clear" message.

---

## CI Failure Triage — Recurrence-Aware but FIX-FIRST (MANDATORY)

A few standing backend product bugs and a handful of env/timing flakes recur every
build. The registry (`ci/known-failures.json`) exists so you don't re-diagnose those
from scratch each run — but it is a **prior to re-confirm, never a verdict that lets a
failure sit red unexamined.** Classifications go stale (a UI redesign can turn a
long-standing "product bug" into a fixable test bug; a 500-ing backend recovers), and
blindly trusting a stale "leave failing" label forever is an **infinite loop of wrong
information.** So: **try to reproduce and fix each failure on its own merits first; use
the registry to re-confirm and to avoid duplicate tickets, not to skip.**

Before triaging any CI failure (including the `/ci` workflow):

1. **Run the registry diff**: `python3 ci/triage.py` (add `--build N` for a specific
   build). It matches the build's Allure failures against `ci/known-failures.json` and
   splits them into NEW vs. known.
2. **Deep-triage every `🚨 NEW / UNTRIAGED` failure from scratch — AND re-confirm every
   KNOWN failure still reproduces this build before deferring to its label:**
   - **test-bug** → always attempt the fix (it's ours); never leave it red because it's
     "known".
   - **product-bug** → re-verify with a cheap live probe (curl the endpoint / run the one
     mapped test, e.g. `KnownBugFlowTest`). Still fails the same way → keep it. Now
     passes → candidate-resolved (step 4). Different signature or now fixable (e.g. a
     stale selector after a UI change) → the label is STALE: fix it / re-classify,
     don't defer.
   - **flake** (env/timing) → re-confirm by *trace-signature match* (re-running just
     re-flakes); if the signature changed, investigate.
3. **Keep `ci/known-failures.json` current**: add new failures (`python3 ci/triage.py
   --update` appends a stub + refreshes occurrence counts), and update any entry whose
   reality changed (new signature, now-fixable, reclassified) so the wrong label can't
   loop again.
4. **Candidate-resolved**: if `triage.py` reports a known failure that PASSED and it
   stays green across runs, remove its entry from the registry.
5. Exit code is non-zero only when there are NEW failures — automation can still gate on
   "is there anything new?", but a zero exit does NOT mean "skip the known ones": they
   still get the cheap re-confirmation in step 2.

`classification` values: `product-bug` (real backend defect — leave failing *after*
re-confirming it still reproduces), `flake` (env/timing — leave failing, re-confirm by
signature), `test-bug` (ours to fix — always attempt), `untriaged` (needs classification).
QA_IO_VN_EOF

mkdir -p "commands"
cat > "commands/README.md" <<'QA_IO_VN_EOF'
# Command specs

Seven ready-to-adapt slash-command specs. Drop them into `.claude/commands/` (Claude Code)
or your agent's equivalent, then replace the placeholder vocabulary (`APP-A`/`APP-B`,
`https://app-a.example.com`, `PROJ`, the example status pipeline) with your project's values
— see [`../ADOPTION.md`](../ADOPTION.md), Step 5. Keep the gates and honesty rules verbatim:
they are the workflow.

| Spec | Command | Stage |
|---|---|---|
| [create.md](create.md) | `/create <ticket>` | Author automated coverage from a dev ticket, tracked by a linked task |
| [manual-test.md](manual-test.md) | `/manual-test <ticket>` | Design + execute a manual test charter against the live product |
| [verify.md](verify.md) | `/verify <ticket…>` | Audit real coverage, author what's missing, stable-green gate, close |
| [verify-bug.md](verify-bug.md) | `/verify-bug <ticket>` | Re-run a bug's mapped test; auto-advance to Done on stable green |
| [ci.md](ci.md) | `/ci [x] [build]` | Triage the CI build: fix test bugs, write product-bug tickets |
| [bug.md](bug.md) | `/bug` | File the bug store into Jira — the one command that asks first |
| [report.md](report.md) | `/report [window]` | Weekly plain-English report reconstructed from the git diff |

All seven expect the connector scripts at `ci/` in the adopting repo (this repository ships
them in [`../toolkit/`](../toolkit/) — copy that folder to `ci/`).
QA_IO_VN_EOF

cat > "commands/create.md" <<'QA_IO_VN_EOF'
---
description: From a Jira dev/implementation ticket, open a linked AutoTask at IN PROGRESS, autonomously author the test cases that cover it (right layer, live-inspected selectors, full POM conventions), verify locally, then — only if every new test passes — move the AutoTask to TO TEST for your manual review; if any test is red or blocked, leave it at IN PROGRESS.
argument-hint: "<JIRA-URL | KEY> [--no-jira] [--dry-run] [--layer api|db|e2e]"
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Skill, mcp__playwright__browser_navigate, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code_unsafe, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_type, mcp__playwright__browser_wait_for, mcp__playwright__browser_console_messages, mcp__playwright__browser_take_screenshot
---

# Create test cases from a Jira ticket, tracked by a linked AutoTask

*Bash snippets below show the reference stack (Java + Maven + JUnit 5 + Playwright-Java).
Substitute your stack's equivalent commands — see `WORKFLOW.md` §6, "Stack adapter" — the
phases, gates, and layer decisions are what to keep.*

You take a Jira **implementation ticket** (the story/spec written for Dev) and produce the
automated tests that cover it — the framework's normal authoring workflow — tracking the work
as a **linked AutoTask** (an issue type for tracking test work — substitute whatever your
tracker uses) whose status mirrors real progress. Fully autonomous, no approval stops. The
AutoTask lifecycle:

1. **Open it at IN PROGRESS first** (before implementing), linked to the dev ticket — so the
   board shows the test work has started.
2. Author the tests (live inspection → Page Objects + Test classes → local verify).
3. **Move it to TO TEST only when every new test passes** — the review gate (assigned to you)
   where you manually validate the tests and close it. **If any new test is still red or
   blocked** (env not ready, feature not deployed, live product bug, un-stabilized flake),
   **leave the AutoTask at IN PROGRESS** — do not advance it. TO TEST means "the tests are green
   and ready for review"; a red/blocked test is not done.

Be honest in the final report and the AutoTask about what is green vs. blocked.

Reads the ticket with `ci/jira.py get`; the AutoTask uses `ci/jira.py create` + `link` (open)
and `ci/jira.py advance` (move to TO TEST). Credentials: gitignored `.claude/jira.env` (see
`ci/INTEGRATIONS.md`). If a Jira call errors with "Missing required key … JIRA_TOKEN", the env
isn't filled in — report and stop; never invent credentials.

Use a **TodoWrite** list to track the phases below.

## Argument parsing (do this first)

Raw arguments: `$ARGUMENTS`

- **Target** = first non-flag token. Extract the Jira key: from `.../browse/KEY` (e.g.
  `https://your-org.atlassian.net/browse/PROJ-123`), from `.../projects/XXX/...PROJ-123`, or a
  bare `^[A-Z][A-Z0-9]+-\d+$`. If you can't extract a key, stop and ask for the ticket key.
- Flags:
  - `--no-jira` — author + verify the tests, but do NOT create the AutoTask (code only).
  - `--dry-run` — read the ticket, inspect, and print the **test-case design + AutoTask plan**
    only. Write no files, create nothing. (Overrides "fully autonomous".)
  - `--layer api|db|e2e` — force the test layer instead of deciding it in Phase 2.

Creating the AutoTask is outward-facing but intended: invoking `/create` (without `--no-jira`
/`--dry-run`) authorizes it. It is opened at **IN PROGRESS** while you implement and moved to
**TO TEST** only when **every new test passes** — a review gate, not auto-done — so you manually
validate and close it. If any new test is red or blocked, it stays at **IN PROGRESS**.

---

## Phase 1 — Load the dev ticket

```bash
python3 ci/jira.py get <KEY>
```
Read the **Summary**, **Description** (requirements / acceptance criteria / steps), and any
**Component**/labels. Determine the **System** (APP-A · APP-B · …) and the feature/area.
Restate in 2–3 lines: what is being built and the concrete acceptance criteria you will cover.
If the description is thin, derive testable criteria from the summary and say you did so.

---

## Phase 2 — Decide the test layer(s)  (CLAUDE.md → Test Architecture Boundaries)

Map each acceptance criterion to the **lowest sufficient layer** — do not write E2E for what
belongs lower, and do not duplicate API coverage in E2E:

| Layer | Use for | Package |
|---|---|---|
| **API / Integration** | CRUD contracts, validation, error codes, request/response schemas | `com.yourco.automation.api.*` (or your messaging publisher helper for message-driven contracts) |
| **DB** | Persistence/sign invariants, ledger contracts | `com.yourco.automation.database.*` |
| **E2E (Playwright)** | Happy-path user flow, cross-module, what only the UI can prove | feature/e2e package under the system |

Default to API/DB for backend behavior; reserve E2E for the critical happy path. Pick the
**System → Base class** (`AppATestBase`/`AppBTestBase`, or standalone `BaseAPITest` / no-base
DB test — keep UI, API, and DB tests in their separate packages; never extend
`PlaywrightTestBase` directly). List the planned classes + one line per test case (its
assertion). With `--dry-run`, stop after Phase 3 and print this design + the Phase 2.5
AutoTask plan.

---

## Phase 2.5 — Open the AutoTask at IN PROGRESS (skip if `--no-jira` or `--dry-run`)

Before writing any test code, open the tracking AutoTask at **IN PROGRESS** and link it to the
dev ticket, so the board shows the test work has started. Assignee + reporter = you; no
priority (AutoTask has none); current active sprint. In the example workflow used here,
`IN PROGRESS` is a single transition from the initial state, so `--status "IN PROGRESS"` (not
a full path) is enough — confirm your own workflow once with
`python3 ci/jira.py transitions <KEY>`.

```bash
cat > /tmp/autotask-desc.txt <<'EOF'
Automated test coverage for <DEV-KEY> — <feature>.

Plan (acceptance criteria to cover):
- <AC / behavior> -> <planned Class#case>
- ...

Status: IN PROGRESS — authoring the tests. Will move to TO TEST when implementation is complete.
Relates to <DEV-KEY>.
EOF

python3 ci/jira.py create \
  --type AutoTask --assignee me --reporter me \
  --summary "Automated tests: <feature> (<DEV-KEY>)" \
  --description-file /tmp/autotask-desc.txt \
  --sprint auto --status "IN PROGRESS" \
  --labels ci-authored,automation,<system-slug> --json
# link it to the dev ticket (AutoTask relates to the dev story):
python3 ci/jira.py link <AUTOTASK-KEY> --to <DEV-KEY> --type Relates
```

Record the returned `<AUTOTASK-KEY>` — you move it to TO TEST in Phase 6. If the create note
reports the sprint or IN PROGRESS status wasn't set, report it and continue authoring.

---

## Phase 3 — Inspect before authoring (MANDATORY)

Never guess selectors, field ids, endpoints, or schemas. Per CLAUDE.md:

- **UI:** check your selector reference doc (e.g. `AI_PLAYWRIGHT_REF.md`), the existing Page
  Object under `src/main/java/com/yourco/automation/ui/pages/<system>/`, and
  `config/application.properties` FIRST. Then confirm live with `browser_navigate` +
  `browser_evaluate` / `browser_run_code_unsafe` (bundle actions; `browser_wait_for` to poll,
  not repeat snapshots). A local checkout of the frontend source, if you have one, can confirm
  real element ids without a browser.
- **API/DB:** confirm the real endpoint (verb, path, payload, status) or the DB
  table/columns against the live service before asserting on them.

Record the confirmed selectors/ids/endpoints you will use.

---

## Phase 4 — Implement the tests (autonomous)

Follow **every** rule in `CLAUDE.md` and, when writing/editing any `*Page.java`, apply your
Page Object clean-code checks. Non-negotiables:

- Page Objects extend `BasePage`, live in `com.yourco.automation.ui.pages.<system>`; selectors
  are `private static final`; domain values are `public static final`; every public action has
  an Allure `@Step` + a `logger.info` and returns `this`/next PO (never `void`); real `visit()`
  (direct `navigateWithRetry(url,…)` using the `ConfigManager` URL key — never hardcoded, never
  click through menus) and a real `isLoaded()`; table rows returned as Java **records**.
- Tests: correct base class (never `PlaywrightTestBase` directly); `@Tag` (e.g.
  `@Tag("APP-A")`); class-level `@DisplayName "{System} - {Big} - {Small}"` (system prefix
  required); `test…`/`should…` methods; `assertTrue(cond, "message")` always with a message;
  `try/finally` cleanup for any state mutation/modal; minimal `setUp()`; own your test data
  (seed → assert → clean up).
- Use the `BasePage` wait methods (never `waitForTimeout`); the dropdown decision tree; no
  magic strings; explicit imports only.
- Credentials and URLs always come from your config/env files via `ConfigManager` — never
  inline them.

Write incrementally (small batches), not all at once.

---

## Phase 5 — Format & verify locally  (headless, background, reruns off)

1. `mvn spotless:apply` on touched files; then `mvn checkstyle:check` for star/unused imports.
2. Set `JAVA_HOME` to the JDK your `pom.xml` targets (e.g. JDK 21). Run the new tests
   **headless**, **reruns disabled**, in the **background** (`run_in_background: true`); read
   the log + `target/surefire-reports/*.txt` once it finishes:
   ```bash
   mvn test -Dtest='NewClass#method,…' -Dheadless=true -Dsurefire.rerunFailingTestsCount=0 -q \
     >/tmp/create_verify.log 2>&1
   ```
3. Iterate to green. For UI tests, run the **3× stability loop** (cold login/context flake).
4. **Honesty + the TO TEST gate:** a test only counts as passing if it is actually **green
   locally**. If a test can't pass because the feature isn't deployed / the env isn't ready / it
   hit a live product bug, do NOT fake it green and do NOT move the AutoTask to TO TEST — still
   author the test asserting the correct expected behavior, record the blocked status truthfully
   in the Phase 6 comment + the Phase 7 report, and **leave the AutoTask at IN PROGRESS**. The
   AutoTask advances to TO TEST **only when every new test is green** (Phase 6). Never claim
   green on an unverified or feature-missing test.

---

## Phase 6 — Advance to TO TEST only when every new test passes (skip if `--no-jira` or `--dry-run`)

**Gate (definition of done for this authoring task):** the AutoTask moves to **TO TEST** only if
**every** new test passes locally — green, and (for UI tests) stable across the 3× loop. If
**any** new test is failing or blocked (env not ready, feature not deployed, live product bug, a
flake you couldn't stabilize), **leave the AutoTask at IN PROGRESS** — do **not** advance it. TO
TEST means "the tests are green and ready for your manual review"; a red or blocked test is not
done.

Either branch: **first record the final coverage + honest verification result** as a comment on
the AutoTask. Then advance only if the gate is met.

**A) All new tests green → comment, then walk IN PROGRESS → TO TEST:**
```bash
cat > /tmp/autotask-done.txt <<'EOF'
Implementation complete — all new tests green:
- <LAYER> <Class#case> — <what it asserts> — PASS
- ...

Files:
- <path/to/NewTest.java>
- <path/to/NewPage.java>

Local verification: <e.g. 4/4 green headless, stable 3x>.
Moving to TO TEST for manual review — close when validated.
EOF
python3 ci/jira.py comment <AUTOTASK-KEY> --body-file /tmp/autotask-done.txt

# Advance IN PROGRESS -> TO TEST. If your workflow has no single transition to "TO TEST",
# walk the '>'-delimited route (jira.py hops each one). Example route — discover your own
# once with: python3 ci/jira.py transitions <KEY>
python3 ci/jira.py advance <AUTOTASK-KEY> \
  --path "Code Review>TECHNICAL VALIDATION>TO DEPLOY>TO TEST"
```

**B) Any new test failing/blocked → comment the honest status, then STOP (stay at IN PROGRESS):**
```bash
cat > /tmp/autotask-blocked.txt <<'EOF'
Tests authored — NOT yet all green, so this stays at IN PROGRESS:
- <LAYER> <Class#case> — <what it asserts> — PASS
- <LAYER> <Class#case> — <what it asserts> — RED/BLOCKED: <why, e.g. backend create returns HTTP 500>

Files:
- <path/to/NewTest.java>

Local verification: <e.g. 3/4 green; 1 blocked by <reason>>.
Staying at IN PROGRESS until every new test is green. What has to change for the blocked
case(s) to pass: <e.g. PROJ-456 backend create fixed → the happy-path test flips green with no
test change>.
EOF
python3 ci/jira.py comment <AUTOTASK-KEY> --body-file /tmp/autotask-blocked.txt
# No `advance` — leave the AutoTask at IN PROGRESS.
```

**Status path (example workflow).** From `IN PROGRESS` an example route to `TO TEST` is
`Code Review → TECHNICAL VALIDATION → TO DEPLOY → TO TEST` (the full chain from creation being
`<initial state> → IN PROGRESS → Code Review → TECHNICAL VALIDATION → TO DEPLOY → TO TEST`) —
discover your own once with `python3 ci/jira.py transitions <KEY>` and update the route. If
`advance` reports it stopped early (a hop's transition wasn't available — e.g. the workflow
changed) report the status it actually reached and recommend the manual move; don't force other
transitions.

---

## Phase 7 — Report

Print:
- The dev ticket (key + feature) and the acceptance criteria covered.
- A table of test cases created: **Layer · Class · Case · Assertion**.
- Files added/changed (for the diff).
- Local verification result (green ×N / blocked-with-reason — honest).
- The **AutoTask**: key + URL, assignee (you), sprint, that it's **Relates**-linked to
  `<DEV-KEY>`, and its status — **TO TEST** (awaiting your manual review to close) **only if
  every new test is green**, otherwise **IN PROGRESS** with the red/blocked case(s) named and
  what has to change for them to pass.

Honesty rule (same as `/ci`): if verification is partial or blocked by the environment, say
exactly that; never claim green on an unverified or feature-missing test — and in that case the
AutoTask stays at IN PROGRESS, not TO TEST.
QA_IO_VN_EOF

cat > "commands/manual-test.md" <<'QA_IO_VN_EOF'
---
description: Manually test a Jira ticket against the live product — derive structured manual test cases from the ticket's acceptance criteria, execute each one live via Playwright MCP (or curl for API-shaped criteria), record per-case verdicts with evidence, comment the result sheet on the ticket, and advance it to Done only when every case passes. Writes no test code — use /create to author automated coverage, /verify to audit and close with automation.
argument-hint: "<JIRA-URL | KEY> [--cases-only] [--no-close] [--no-jira] [--no-teams] [--dry-run]"
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite, mcp__playwright__browser_navigate, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code_unsafe, mcp__playwright__browser_snapshot, 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_wait_for, mcp__playwright__browser_console_messages, mcp__playwright__browser_network_requests, mcp__playwright__browser_take_screenshot
---

# Manually test a ticket — design the cases, run them live, report the verdict

You are the manual tester for a Jira ticket: you turn its acceptance criteria into a
structured **manual test charter**, execute every case **against the live product** (browser
via Playwright MCP, or curl when a criterion is an API contract), and report an honest
per-case verdict with evidence. You write **no test code** — that is /create's job; /verify
audits automated coverage. What this command produces is what a human QE would: a charter, an
execution record, and a ticket update.

Connectors: `ci/jira.py` (get, comment, attach, transitions, advance) and `ci/teams.py`.
Credentials live in gitignored `.claude/jira.env` / `.claude/teams.env` (setup:
`ci/INTEGRATIONS.md`). If a call errors with "Missing required key … JIRA_TOKEN" (or
`TEAMS_WORKFLOW_URL` missing), the env isn't filled in — say so and stop; never invent
credentials.

Use a **TodoWrite** list: one entry per phase, plus one per test case in Phase 3.

## Argument parsing (do this first)

Raw arguments: `$ARGUMENTS`

- **Target** = first non-flag token. Resolve to a Jira key: `selectedIssue=<KEY>` →
  `/browse/<KEY>` → `/issues/<KEY>` → bare `^[A-Z][A-Z0-9]+-\d+$` (last match wins for URLs).
  `ci/jira.py get` takes a **bare key only** — extract it from the URL yourself. No key
  extractable → say so and stop.
- Flags:
  - `--cases-only` — design and persist the charter (Phases 1–2), execute nothing.
  - `--no-close` — never transition the ticket; comment the verdict and recommend the move.
  - `--no-jira` / `--no-teams` — skip those writes (the ticket is still read).
  - `--dry-run` — design and execute for real, but write **nothing** external (no charter
    edits committed to Jira/Teams; still write the local charter file) and print what would
    be sent.

**Authorization:** invoking `/manual-test` (without `--no-jira`/`--dry-run`) authorizes the
Jira comment + evidence attachment, the Teams card, and — **only when every executed case
passes** — advancing the ticket through its remaining workflow stages to Done (same standing
authorization as /verify and /verify-bug; `--no-close` opts out). A failed, blocked, or
partially executed run must NEVER advance or close the ticket.

---

## Phase 1 — Load the ticket and distill what to test

```bash
python3 ci/jira.py get <KEY>
```

Read the **Summary**, **Description** (requirements / acceptance criteria / steps /
expected–actual), **Environment**, components/labels. Determine the **System**
(APP-A · APP-B · …) and the feature/area. Then:

1. Distill the **testable acceptance criteria** — concrete, checkable statements. A thin
   description → derive criteria from the summary and say you did so. A ticket too vague to
   yield even one checkable statement → say so and stop; never invent acceptance criteria.
2. Check for known interference: `grep -l "jira_key: <KEY>" bugs/*.md`, plus a quick scan of
   `ci/known-failures.json` and project memory for the feature. A known live product bug in
   the same area is **context you must carry into Phase 3** — a case failing on a documented
   pre-existing defect is reported as failing with that reference, not re-discovered from
   scratch.
3. Note the ticket's current status (it decides the Phase 5 advance path).

---

## Phase 2 — Design the manual test charter

Write the charter to **`manual-tests/<KEY>.md`** (create the folder if missing; re-running
the command updates the same file — the charter is a living document, the newest execution
record is appended). Structure:

```markdown
# Manual Test Charter — <KEY>: <ticket summary>

System: <APP-A | APP-B | …> · Feature: <area>
Source: <JIRA_BASE>/browse/<KEY> · Charter updated: <date>

## Acceptance criteria under test
- AC1 — <statement>
- ...

## Test cases

### <KEY>-MT-01 — <title>  [Priority: High|Medium|Low]
- **Covers:** AC1
- **Preconditions:** <state, data, user>
- **Steps:** 1. … 2. … (user-level actions, no tool jargon)
- **Expected:** <observable result>
```

Design rules:

- Cover **every** acceptance criterion with at least one case; add **negative/validation**
  cases (bad input, empty state, denied action), a **boundary** case when a limit/format is
  in play, and a **persistence check** (reload or re-query after the change — did it stick?).
- Steps are **user-level** and reproducible by a human — no selectors, no wait budgets.
- Test data is **owned by the run**: prefix anything you create `AUTOTEST_`, and plan its
  cleanup as the final step of the case that created it.
- Keep it proportionate: a one-line config ticket does not need 12 cases; a new CRUD screen
  does not get away with 2. State the intended scope in one line above the cases.

With `--cases-only`, print the charter and stop here.

---

## Phase 3 — Execute every case against the live product

Follow your project's **Playwright MCP Efficiency Rules** — check your selector reference
(e.g. `AI_PLAYWRIGHT_REF.md`), the Page Objects, and `config/application.properties` for
URLs and selectors **before** any snapshot; bundle actions with `browser_run_code`; poll
with `browser_wait_for`; snapshot only as last resort (`depth: 3`). Log in per your system
reference, using credentials from your config/env files (including any IdP/OTP flow your
environment requires). Navigate the SPA root once; note whether your app's routes are
path-based or hash-based.

Per case, in charter order:

1. Establish the preconditions (seed data if the case needs it — `AUTOTEST_` prefix).
2. Execute the steps as a user would. A criterion that is purely an API contract may be
   executed with `curl` instead of the browser — say so in the record.
3. Compare observed behavior to **Expected** and record the verdict:
   - **PASS** — observed matches expected. Only for cases you actually executed end-to-end.
   - **FAIL** — observed contradicts expected. Capture a screenshot to
     `.claude/ci-report/<KEY>-manual-<CASE>.png`, note the exact observed behavior, console
     errors, and the failing network call if visible (`browser_network_requests`). Check
     Phase 1's known-bug context before declaring a new defect.
   - **BLOCKED** — the case could not be executed (env down, feature not deployed, missing
     fixture you cannot seed). Name the blocker precisely; `curl` the base URL when an
     environment drop is plausible so the record shows env-vs-product.
4. Clean up any data the case created, even on FAIL (best effort; note if cleanup failed).

Also capture **one overall evidence screenshot** of the feature in its final healthy state
(`.claude/ci-report/<KEY>-manual.png`) when the run is a pass.

Append the **Execution Record** to the charter file:

```markdown
## Execution Record — <date>
Environment: <system + base URL> · Build: <if known> · Method: Playwright MCP (+ curl)

| Case | Verdict | Observed |
|---|---|---|
| <KEY>-MT-01 | PASS | <one line> |
| <KEY>-MT-02 | FAIL | <one line + evidence path> |

Overall: PASSED | FAILED (<n> case(s)) | BLOCKED | PARTIAL (<executed>/<total>)
```

**Overall verdict:** PASSED only when every case executed and passed. Any FAIL → FAILED. No
FAIL but ≥1 BLOCKED → BLOCKED/PARTIAL. Never skip a case silently — a case you didn't run is
BLOCKED with a reason, not omitted.

---

## Phase 4 — Record the result to Jira (skip if `--no-jira` or `--dry-run`)

1. Attach evidence: `python3 ci/jira.py attach <KEY> --file .claude/ci-report/<KEY>-manual.png`
   (and each failure screenshot).
2. Comment the result sheet (heredoc → file → `--body-file`, never inline):

```
Manual test result: <PASSED | FAILED (n/N) | BLOCKED | PARTIAL (n/N executed)>

Charter: <N> cases covering <the ACs> (manual-tests/<KEY>.md)
Method: manual execution via browser (+ curl for API criteria), <system> test environment, <date>

Results:
- <KEY>-MT-01 <title> — PASS
- <KEY>-MT-02 <title> — FAIL: <observed vs expected, one line>
- ...

<For each FAIL, a short defect block: Steps to Reproduce / Actual / Expected — user-level,
ready to lift into a bug ticket. Reference the existing bug/Jira key if Phase 1 matched one.>

Evidence: attached. Caveats: <or "None">
```

3. **Transition — only on overall PASSED** and without `--no-close`: read the current status
   (`python3 ci/jira.py get <KEY>`), slice your workflow pipeline — example:
   `IN PROGRESS>Code Review>TECHNICAL VALIDATION>TO DEPLOY>TO TEST>DONE` (discover your own
   once with: `python3 ci/jira.py transitions <KEY>`) — to start after the
   current status, then one call:
   `python3 ci/jira.py advance <KEY> --path "<remaining>>DONE"`. `advance` skips reached
   waypoints and stops at the first unavailable hop — report exactly where it landed;
   stopping short is a Jira-workflow gate, not a failed test.
4. **On FAILED:** do not transition. Do **not** create Bug issues from here — recommend the
   defect block for `/bug` (if a CI bug file exists) or a manual filing, and name the failing
   cases in the summary. A defect found by manual test on a ticket in review usually means
   the ticket goes back to the developer — recommend that move, don't force it.

---

## Phase 5 — Teams card (skip if `--no-teams`)

```bash
python3 ci/teams.py --status <fixed|reproduces|inconclusive> --bug "<KEY>" \
  --system "<APP-A|APP-B|…>" \
  --title "Manual test: <ticket summary, concise>" \
  --summary "<n>/<N> cases passed; <one-line outcome>. Charter: manual-tests/<KEY>.md" \
  --url "<JIRA_BASE>/browse/<KEY>"
```

Status mapping: PASSED → `fixed` (green) · FAILED → `reproduces` (red) · BLOCKED/PARTIAL →
`inconclusive` (amber). With `--dry-run`, append `--dry-run` to preview the payload.

---

## Phase 6 — Summary

Print:

- Ticket (key + one-line statement of what was under test) and the System.
- Charter: N cases, which ACs they cover, path to `manual-tests/<KEY>.md`.
- Per-case verdict table (case · verdict · one-line observed).
- Overall verdict, and for FAILED/BLOCKED: exactly what failed or blocked, with evidence
  paths and any matched known bug.
- What was written back: comment id, attachments, advance result (full hop list, or
  stopped-at + why, or "recommended: …"), Teams status — or the dry-run note.
- Follow-ups: `/bug` or manual filing for new defects; `/create` when the feature deserves
  automated coverage (a manual PASS is a point-in-time check, not regression protection).

**Honesty rule (same as /ci and /verify):** a case is PASS only if you executed it
end-to-end this run and observed the expected result — never infer a pass from code, an old
run, or a neighboring case. Blocked is a legitimate verdict; name the blocker plainly. A
false PASSED that advances a broken ticket to Done is worse than any honest FAILED.
QA_IO_VN_EOF

cat > "commands/verify.md" <<'QA_IO_VN_EOF'
---
description: Verify a Jira ticket is genuinely delivered — audit whether automated coverage actually asserts its Expected result, author the missing test cases when it does not, run everything until it is stable green, then advance the ticket to Done. Accepts several tickets at once. Use /verify-bug instead when you only want to re-run a bug's already-mapped test.
argument-hint: "<JIRA-KEY | Jira URL | search text> [more keys...] [--runs N] [--no-new-tests] [--no-close] [--no-jira] [--no-teams] [--dry-run]"
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Skill, mcp__playwright__browser_navigate, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code_unsafe, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_type, mcp__playwright__browser_wait_for, mcp__playwright__browser_console_messages, mcp__playwright__browser_take_screenshot
---

# Verify a ticket end-to-end — cover it, prove it, then close it

*Bash snippets below show the reference stack (Java + Maven + JUnit 5 + Playwright-Java).
Substitute your stack's equivalent commands — see `WORKFLOW.md` §6, "Stack adapter" — the
stability gate and honesty rules are what to keep.*

You answer one question per ticket: **is this actually delivered, and is there a test that
will keep it delivered?** That is two things, and both must be true before anything moves:

1. **It works now** — the ticket's *Expected result* holds against the live environment.
2. **It stays working** — an automated test asserts that Expected result, and that test is
   green and stable.

When (2) is missing you **write it**. A ticket whose only evidence is "I clicked it once and
it looked fine" is not verified — it is unprotected, and the next regression finds it in
production instead of in CI. When both hold across `--runs` clean runs, **advance the ticket
all the way to Done**.

**How this differs from `/verify-bug`:** `/verify-bug` re-runs a bug's already-mapped test to
answer "does it still reproduce?" — it assumes the coverage exists and is correct. `/verify`
does not assume: it audits the coverage first, treats a **stale map as no coverage**, and
authors what is missing before judging anything. Use `/verify-bug` for a quick recurrence
check on a CI-filed bug; use `/verify` to close a ticket out. Both remain valid; neither
replaces the other.

Connectors (stdlib; creds in gitignored `.claude/*.env`, setup in `ci/INTEGRATIONS.md`):

- `ci/jira.py` — `get`, `search`, `comment`, `transitions`, `transition`, `advance`, `attach`.
- `ci/teams.py` — Adaptive Card to the Teams Workflow URL (`--dry-run` previews).
- `ci/_bugfile.py` — parses `bugs/bug-NNN.md` (the local bug store).

If a connector reports "Missing required key" / "TEAMS_WORKFLOW_URL missing", the env file is
not filled in — say so and stop. Never invent credentials.

Track the phases with **TodoWrite**, one entry per ticket per phase.

---

## Argument parsing (do this first)

Raw arguments: `$ARGUMENTS`

**Targets** = every non-flag token that resolves to a Jira key. Unlike `/verify-bug`, this
command takes **several tickets in one run** — verify each independently and report per
ticket. Resolution, per token:

- **Jira URL** (e.g. `https://your-org.atlassian.net/browse/PROJ-123`) →
  `selectedIssue=<KEY>` → `/browse/<KEY>` → `/issues/<KEY>` → last
  `^[A-Z][A-Z0-9]+-\d+` in the string.
- **Bare key** `^[A-Z][A-Z0-9]+-\d+$` → use as-is.
- **Neither** → treat the remaining non-flag text as search text and find the issue with
  `ci/jira.py search --jql "text ~ '<phrase>'"`; say which key you picked.

```bash
printf '%s\n' $ARGUMENTS | grep -oE '[A-Z][A-Z0-9]+-[0-9]+' | sort -u
```

Flags:
- `--runs N` — clean runs required before Done (default **3**).
- `--no-new-tests` — audit and run only; report the coverage gap instead of filling it. A
  ticket with no coverage then ends **not verified**, never Done.
- `--no-close` — verify and record, but never transition; recommend the move instead.
- `--no-jira` / `--no-teams` — skip those writes (still read the issue).
- `--dry-run` — do the real verification, write nothing anywhere, print what you would send.

---

## Phase 1 — Read the ticket, and understand what "done" means for it

```bash
python3 ci/jira.py get <KEY>
```

Extract, in the ticket's own words: **Expected result**, **Actual result** (for a bug), steps,
environment, and any `Source test:` / `Test reference:` footer. Then cross-reference:

```bash
grep -l "jira_key: <KEY>" bugs/*.md          # local bug store, if CI filed it
grep -n "<feature phrase>" ci/known-failures.json
```

Write down **one testable statement** — the thing that must be true for this ticket to be
done. "Opening the equipment list shows the data without a server error." "Saving a
record returns the record, and the list loads." That sentence is what you will verify and
what the new test, if any, must assert. If the ticket is too vague to yield one, say so and
stop — do not invent an acceptance criterion.

Note the ticket's **current status**. A ticket already at DONE still gets fully verified: a
prematurely-closed ticket that still reproduces is a finding worth more than a green tick.

---

## Phase 2 — Coverage audit (the part `/verify-bug` skips)

Find the test(s) that assert the statement from Phase 1. Start from the `source_test`, then
search by feature:

```bash
grep -rn "<feature>" src/test/java --include='*.java' -l     # quote the globs — zsh
```

For each candidate, open it and judge it against three questions. **Any "no" means the
coverage does not exist for verification purposes**, regardless of what the ticket's footer
claims:

1. **Does it still exist?** A `source_test` that no longer resolves to a real
   `Class#method` is a stale map — the method was renamed, or removed with a contract
   migration. This is common and easy to miss: the class is still there and still green,
   so the mapping looks alive while the case that mattered is gone.
2. **Does it assert the ticket's Expected result** — not merely something nearby? A page
   that renders its frame after its data call 500s still satisfies `isLoaded()`. A negative
   validation case passing tells you nothing about whether the happy path works.
3. **Would it have failed while the defect was live?** If the answer is no, it cannot be the
   evidence. Reason it through against the ticket's Actual result and say so explicitly.

Record the verdict per ticket: **covered** / **stale map** / **uncovered** / **wrong layer**
(covered, but at a layer that cannot see the defect — see the Test Architecture Boundaries
table in `CLAUDE.md`).

---

## Phase 3 — Author the missing coverage (skip on `--no-new-tests`)

For anything not **covered**, write the test. This is ordinary authoring work and every rule
in `CLAUDE.md` applies — the layer table, the system base classes (`AppATestBase` /
`AppBTestBase`; never extend `PlaywrightTestBase` directly), POM structure, `@Step` +
logging, `private static final` selectors, no magic strings, no `waitForTimeout`, Allure
`@DisplayName` as a plain sentence, `mvn spotless:apply` afterwards.

Specific to verification work:

- **Pick the layer the defect lives at.** A backend 500 belongs in an API/contract test; a
  broken widget belongs in E2E. Do not write an E2E test for something a contract test pins
  better, and do not "verify" a UI symptom purely at the API layer — the user's surface is
  part of the claim.
- **Probe live before you write.** `curl` the endpoint, or use the Playwright MCP browser per
  the efficiency rules in `CLAUDE.md`, and learn the real contract: status codes, payload
  shape, auth requirements, selector ids. Guessing produces a test that fails for reasons
  that have nothing to do with the ticket.
- **Assert the ticket's sentence, not the environment's current data.** Pin the *contract* —
  "a card per favourited item", "the list loads", "the created record reads back" — never
  which specific rows or names happen to exist today. Environment-pinned assertions are how a
  working feature gets filed as a product bug.
- **Make it fail for the right reason.** Before accepting a green, state plainly why this
  assertion would have gone red while the defect was live. If you cannot answer that, the
  test is decoration.
- **Leave the environment as you found it.** Seed what you need, clean it up in `finally` /
  `@AfterEach`, and prefix any created data with `AUTOTEST-`.

Reuse before you add: an existing helper (`src/test/java/com/yourco/automation/core/helpers/`)
or Page Object usually already knows the contract — extend it rather than duplicating it.

---

## Phase 4 — Stability gate

Run **every** test that covers the tickets in scope — the pre-existing ones and everything you
just wrote — `--runs` times, headless, on the JDK your build targets, **reruns off** so a
flake shows as a failure. Run it in the background (the `/ci` rule) and keep the per-class
results from each run.

```bash
export JAVA_HOME=/path/to/your/jdk    # match your pom's target, e.g. JDK 21
SEL="ClassA#method,ClassB,ClassC"
for i in 1 2 3; do
  mvn test -Dtest="$SEL" -Dheadless=true -Dsurefire.rerunFailingTestsCount=0 -q \
    > /tmp/verify_all_$i.log 2>&1
  echo "run $i exit=$?"
  grep -h "Tests run:" target/surefire-reports/*.txt
done
```

Classify per ticket:

- **All runs green → verified.** The ticket's statement holds and is now protected.
- **Any red that matches the ticket's Actual result → still reproduces.** The ticket is not
  done. Do not advance it; report the failure with the evidence.
- **Red for an unrelated reason** (env down, seed missing, a different defect) →
  **inconclusive**. Name exactly what blocked it — `curl` the environment when an environment
  drop is plausible. Never guess a verdict.
- **Green sometimes → flaky, not verified.** Stabilise the test or report it as flaky. Never
  raise `rerunFailingTestsCount` to launder a flaky pass into a green.

For a UI ticket, corroborate with one live screenshot of the working screen
(`.claude/ci-report/<KEY>-verify.png`) — good evidence for the reviewer, and cheap.

---

## Phase 5 — Record and close (skip writes on `--no-jira` / `--dry-run`)

Per ticket:

1. **Attach evidence** — screenshot, or a saved log excerpt:
   ```bash
   python3 ci/jira.py attach <KEY> --file .claude/ci-report/<KEY>-verify.png
   ```
2. **Comment** (heredoc → file → `--body-file`), in this order:
   - **Verification result:** Verified (stable green) | Still reproduces | Inconclusive | Flaky
   - **Coverage:** what asserted it — name the test(s), and say plainly whether they already
     existed, were **newly written for this ticket**, or replaced a stale mapping. If you
     wrote tests, list the files.
   - **Method:** runs and results (`3/3 green`), environment/build, JDK/browser, login type.
   - **Observed:** what happened vs. the ticket's Expected result, in 2–4 plain sentences.
   - **Evidence:** attachment / log names.
   - **Caveats:** anything not covered, or `None`.
3. **Advance to Done** — only on **verified** (all `--runs` green), and only without
   `--no-close`/`--dry-run`. Invoking this command authorizes the full walk; do not stop to
   ask, and do not settle for a single hop:
   ```bash
   python3 ci/jira.py get <KEY>            # current status
   python3 ci/jira.py advance <KEY> --path "<remaining hops>>DONE"
   ```
   Example bug pipeline — discover your own project's once with
   `python3 ci/jira.py transitions <KEY>`:
   `IN PROGRESS>Code Review>TECHNICAL VALIDATION>TO DEPLOY>TO TEST>DONE`.
   Slice it to start at the ticket's current status. `advance` skips waypoints already passed
   and stops at the first hop with no matching transition — read its per-hop output and report
   exactly where it landed. Stopping short is a Jira-workflow gate, not a failed verification:
   say which status it reached and what blocked the next hop.
   - Already at DONE and verified → nothing to move; say it was confirmed, not closed.
   - Already at DONE but **still reproduces** → do not reopen silently. Lead the report with
     it and recommend reopening; that is the finding of the run.
4. **Update the local bug store** when a `bugs/bug-NNN.md` maps to the key: set
   `status: fixed` and append `verified_fixed: <today> (<N>/<N> green via <tests>; advanced
   <KEY> to <status>)`. Recommend the `ci/known-failures.json` candidate-resolved removal;
   leave the actual pruning to `/ci`, which sees the whole build.

New test files are part of the deliverable — name them in the summary so the reviewer knows
what landed alongside the verdict.

---

## Phase 6 — Teams + summary

```bash
python3 ci/teams.py --status <fixed|reproduces|inconclusive> --bug "<KEY>" --system "<APP-A|APP-B|...>" \
  --title "<concise statement>" --summary "<what covered it, how many runs, what you found>" \
  --url "<JIRA_BASE>/browse/<KEY>"
```
Map flaky → `inconclusive`. One card per ticket.

Then print a per-ticket report:

- **Ticket** — key + the one-sentence statement you verified.
- **Coverage** — existing / newly written (name the files) / stale map replaced.
- **Result** — verified (N/N green) | still reproduces | inconclusive | flaky, plus the caveat.
- **Jira** — comment id, evidence attached, the **full hop list** to Done or the status it
  stopped at and why; local bug-file update; Teams post — or, on `--dry-run`, that nothing was
  sent.
- **Findings** — anything you noticed on the way that the reviewer cannot see from the board:
  a stale test mapping, a ticket closed while still broken, coverage that was passing for the
  wrong reason, an environment quirk.

**Honesty rule:** a ticket reaches Done only on `--runs` clean runs of coverage that genuinely
asserts its Expected result. Never advance on one pass, a flaky pass, or a test you weakened
to make green. If the environment blocked you, say so and leave the ticket where it is —
"inconclusive" is a real, useful answer; a false Done is not.
QA_IO_VN_EOF

cat > "commands/verify-bug.md" <<'QA_IO_VN_EOF'
---
description: Verify whether a known bug is fixed by running its mapped automated test (auto-script check), driven by the Jira issue + the local bug store. On a stable green, auto-advance the Jira issue through its remaining workflow stages to Done; otherwise record the verdict. Falls back to live Playwright MCP verification when no test maps. Posts a card to Teams.
argument-hint: "<JIRA-KEY | Jira URL | search text> [--manual] [--runs N] [--no-close] [--transition \"Status\"] [--no-jira] [--no-teams] [--dry-run]"
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__playwright__browser_navigate, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code_unsafe, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_type, mcp__playwright__browser_wait_for, mcp__playwright__browser_console_messages
---

# Verify a bug — auto-script check first, then report to Jira + Teams

*Bash snippets below show the reference stack (Java + Maven + JUnit 5 + Playwright-Java).
Substitute your stack's equivalent commands — see `WORKFLOW.md` §6, "Stack adapter" — the
stability gate and honesty rules are what to keep.*

You verify whether a known bug is **still present or now fixed**, then record the outcome.
The primary check is **automated**: find the test that maps to the bug and run it. A bug
filed by CI has a `source_test` that is **red because of the bug** — when that test turns
**green and stays green**, the bug is fixed. On a stable green you **auto-advance the Jira
issue through every remaining workflow stage to Done** — not just a single hop (see Phase 3).
When no test maps (or `--manual`), fall back to a live Playwright MCP check.

Three connectors do the I/O (all stdlib; creds in gitignored `.claude/*.env`):

- `ci/jira.py` — Jira Cloud REST v3: `get`, `search`, `comment`, `transitions`, `transition`,
  `advance` (walk a `>`-delimited status path, one direct transition per hop — skips a
  waypoint already reached, stops cleanly at the first hop with no matching transition), `attach`.
- `ci/teams.py` — posts an Adaptive Card to the Teams Workflow URL (`--dry-run` to preview).
- `ci/_bugfile.py` — parses `bugs/bug-NNN.md` frontmatter/body (the local bug store).

Setup/troubleshooting lives in `ci/INTEGRATIONS.md`. If a connector errors with
"Missing required key" / "TEAMS_WORKFLOW_URL missing", the env file isn't filled in —
report that and stop; do not invent credentials.

---

## Argument parsing (do this first)

Raw arguments: `$ARGUMENTS`

**Target** = the first non-flag token. Resolve it to a Jira key:

- **Jira URL** (e.g. `https://your-org.atlassian.net/jira/software/projects/PROJ/boards/1?selectedIssue=PROJ-123`)
  → extract the key. Precedence: `selectedIssue=<KEY>` → `/browse/<KEY>` → `/issues/<KEY>`
  → the last `^[A-Z][A-Z0-9]+-\d+` token in the string.
- **Bare key** matching `^[A-Z][A-Z0-9]+-\d+$` (e.g. `PROJ-123`) → use as-is.
- Otherwise → treat the whole non-flag remainder as **search text** (Phase 1 finds the key).

One resolver for URL-or-key:
```bash
KEY=$(printf '%s' "$ARGUMENTS" | grep -oiE '(selectedIssue=|/browse/|/issues/)?[A-Z][A-Z0-9]+-[0-9]+' \
  | grep -oE '[A-Z][A-Z0-9]+-[0-9]+' | head -1)
echo "Resolved Jira key: ${KEY:-<none — treat args as search text>}"
```

Flags:
- `--manual` → skip the auto-script check; verify live with Playwright MCP (old behavior).
  Use when the bug has no mapped test, or the bug is UI-only and best confirmed by eye.
- `--runs N` → how many green runs count as "stable" before closing (default **3**).
- `--no-close` → never transition, even on a stable green; comment the verdict and recommend the move.
- `--transition "Name"` → force this specific transition after verifying (overrides auto-close).
- `--no-jira` → skip all Jira writes (still read the issue; don't comment/attach/transition).
- `--no-teams` → skip the Teams post.
- `--dry-run` → verify for real, but write NOTHING to Jira and POST nothing to Teams; print
  what you *would* send (use `ci/teams.py … --dry-run`).

**Authorization:** invoking this command authorizes the Jira comment + attachment and the
Teams post. It **also authorizes auto-advancing the issue through every intermediate
workflow stage to Done — but only on a stable green** (the mapped test passing `--runs`
times with no failures and no rerun-hiding). This is a deliberate, standing choice — agree
it with your team once and record the decision: intermediate statuses like Code Review /
Technical Validation normally track a human sign-off, and `/verify-bug` collapses them
automatically once the automated + live evidence confirms the fix — do not stop to ask
before doing this, and do not water it down to a single hop. A single green, a flaky pass,
a reproduce, or an inconclusive result must **never** advance or close the issue.

---

## Phase 1 — Load the bug from Jira **and** the local bug store

**Jira (issue of record):**
```bash
python3 ci/jira.py get <KEY>
```
Read Summary, Description (steps / expected / actual), Environment, System. For a CI-filed
bug the description footer carries `Source test:` and a `Test reference:` line — these name
the mapped test even when there is no local file.

**Search text (no key yet):** find the issue, then `get` it:
```bash
python3 ci/jira.py search --jql "text ~ '<phrase>' AND statusCategory != Done"
```
If several match, pick the closest by summary and say which key you chose.

**Local bug store (`bugs/bug-NNN.md`) — the richer local record:**
```bash
grep -l "jira_key: <KEY>" bugs/*.md      # the file whose frontmatter maps to this key
```
If a file matches, read its frontmatter and body — it gives the authoritative `source_test`,
`system`, `severity`, and the plain-English steps/expected/actual. If **no** file maps to the
key, fall back to the `Source test:` / `Test reference:` lines in the Jira description, and
cross-reference `ci/known-failures.json` for the registry entry.

**Determine the mapped test(s) to run.** The signal is the test that is **red *because of*
this bug**:
- The `source_test` (from the local file, else the Jira `Source test:` footer).
- Plus any sibling tests the bug body flags as failing *for the same reason* (e.g. an "Also
  fails identically" list, or a "RED happy-path" contract test). **All** of these must go
  green for the bug to be "fixed."
- **Do NOT** run guard/contract tests that are *green while the bug exists* (they assert the
  broken behavior on purpose — e.g. a `KnownBugFlowTest` that pins the current wrong
  behavior) — a green there proves nothing about the fix.

Restate in one line: the bug (key + symptom), the mapped test(s) you will run, and whether
you're in auto-script mode or `--manual`.

---

## Phase 2A — Auto script check (default; skip if `--manual` or no mapped test)

Convert each `source_test` (`pkg…Class.method`) to a Surefire selector `Class#method`:
```bash
DTEST=$(python3 - "<source_test>" <<'PY'
import sys; p = sys.argv[1].split('.'); print(f"{p[-2]}#{p[-1]}")
PY
)
# Multiple tests → comma-join: 'ClassA#m1,ClassB#m2'
```

Run headless with the JDK your pom targets, **reruns off** so a flake shows as a real
failure (never hide one). Run tests in the **background** (CLAUDE.md `/ci` rule). First a
single confirming run:
```bash
export JAVA_HOME="<path to the JDK your pom targets, e.g. JDK 21>"
mvn test -Dtest="$DTEST" -Dheadless=true -Dsurefire.rerunFailingTestsCount=0 -q \
  >/tmp/verify_<KEY>_1.log 2>&1; echo "run 1 exit=$?"
```

**Classify the run** from the exit code + the Surefire summary in the log:
- **PASS** (exit 0, `Tests run: N, Failures: 0, Errors: 0`) → *candidate-fixed* — go to the stability gate.
- **FAIL** (test assertion/timeout failed) → **still reproduces**. Confirm the failure reason
  matches the ticket's Actual result (don't call it "reproduces" if it broke for an unrelated
  reason — that's a test-bug or env issue → inconclusive).
- **ERROR / build broke / env down** (compilation error, `Connection refused`, no seed data,
  login failure, `net::ERR_ADDRESS_UNREACHABLE`) → **inconclusive**. Name exactly what blocked
  it; `curl` the env when an environment drop is plausible. Do not guess pass/fail.

**Stability gate (only when the first run PASSED).** A single green is a point-in-time
observation, not proof. Run `--runs - 1` more times (default → 2 more, total 3):
```bash
for i in 2 3; do
  mvn test -Dtest="$DTEST" -Dheadless=true -Dsurefire.rerunFailingTestsCount=0 -q \
    >/tmp/verify_<KEY>_$i.log 2>&1; echo "run $i exit=$?"
done
```
- **All `--runs` green → stable green → FIXED.**
- **Any red among them → NOT stable** → the bug still manifests or the test is flaky →
  outcome is **reproduces** (if it fails the ticket's way) or **inconclusive/flaky** (if it
  fails erratically). Either way, **do not close.** Never bump `rerunFailingTestsCount` to
  turn a flaky pass into a "green."

Optionally corroborate a stable green with a quick Playwright MCP spot-check of the fixed
screen and a screenshot (Phase 2B steps 1 & 4) — nice evidence, not required for the verdict.

---

## Phase 2B — Manual live check (fallback: `--manual`, or no mapped test)

Follow your project's **Playwright MCP Efficiency Rules** (CLAUDE.md): check your selector
reference doc (e.g. `AI_PLAYWRIGHT_REF.md`), the relevant Page Object, and
`config/application.properties` for URLs/selectors **before** snapshotting. Log in with
credentials from your config/env files (handle OTP/TOTP if your identity provider requires
it); know whether your SPA's routes are path-based or hash-based and navigate the app root
once before deep-linking.

1. Reproduce the ticket's steps with `browser_navigate` + `browser_evaluate` /
   `browser_run_code_unsafe` in as few round-trips as possible; poll with `browser_wait_for`.
2. Compare **actual** behavior to the ticket's **Expected result**.
3. Decide: **reproduces** (defect still happens) / **fixed** (behaves as Expected) /
   **inconclusive** (blocked by unrelated env issue — say what blocked you).
4. Capture one decisive screenshot: `browser_take_screenshot -> .claude/ci-report/<KEY>-verify.png`.

Manual "fixed" is **not** eligible for auto-close (no stable automated proof) — record it and
recommend the transition. Close automatically only from a stable green in Phase 2A, or when
`--transition` is given explicitly.

---

## Phase 3 — Record the result to Jira (skip if `--no-jira`, `--dry-run`, or no key)

1. **Attach evidence:** the screenshot if you took one, else a short log excerpt saved as a file:
   ```bash
   python3 ci/jira.py attach <KEY> --file .claude/ci-report/<KEY>-verify.png
   ```
2. **Comment** with a structured, plain-language note (heredoc → file → stdin; no inline magic strings):
   ```bash
   python3 ci/jira.py comment <KEY> --body-file /tmp/verify-note.txt
   ```
   Contents, in order:
   - **Verification result:** Fixed (stable green) | Still reproduces | Inconclusive | Flaky (not stable)
   - **Method:** auto-script — `Class#method`, ran N times, results per run (e.g. `3/3 passed`); or Manual (Playwright)
   - **Environment:** system + build/URL checked against, JDK/browser, login type
   - **Observed:** what happened vs. what was expected (2–4 plain sentences)
   - **Evidence:** attached screenshot / log name
   - **Caveats:** any scope limit (or `None`)
3. **Transition — auto-advance to Done (no confirmation needed; this is standing-authorized):**
   - Outcome is **stable green (FIXED)**, and no `--no-close`/`--dry-run`/`--transition` →
     walk the issue all the way to **Done**, not just one hop:
     ```bash
     python3 ci/jira.py get <KEY>                  # current status, e.g. "[Bug | Code Review | High]"
     ```
     Take the canonical Bug pipeline for your project — the path below is an **example**
     (discover your own once with: `python3 ci/jira.py transitions <KEY>`); reuse it as the
     default for every system unless a project's `transitions` output shows different status
     names, in which case build the path from those instead:
     ```
     IN PROGRESS>Code Review>TECHNICAL VALIDATION>TO DEPLOY>TO TEST>DONE
     ```
     Slice that path to start at the issue's **current** status (or the beginning, if the
     current status isn't in the canonical list) and walk it with a single call:
     ```bash
     python3 ci/jira.py advance <KEY> --path "TECHNICAL VALIDATION>TO DEPLOY>TO TEST>DONE"
     ```
     `advance` skips any waypoint the issue is already at and stops at the first hop with no
     matching transition — read its per-hop output. Two outcomes:
     - **Reached DONE** → success; report the full hop list in the summary.
     - **Stopped short** (a hop had no matching transition — e.g. a genuine manual gate not
       present as a transition option) → do **not** treat this as a failure of the
       verification itself. Report exactly which status it reached and what blocked the next
       hop, and note it as a follow-up for a human to move manually. The bug is still FIXED;
       only the Jira transition is incomplete.
   - **Explicit `--transition "Name"`** → do that single hop instead of the full advance
     (confirm it's available first via `ci/jira.py transitions <KEY>`).
   - **Any non-fixed or not-stable outcome** → do **not** transition or advance; recommend the
     move in the summary.

4. **Update the local bug store on a confirmed FIXED verdict** (so the next `/ci` doesn't re-file it):
   - In the mapped `bugs/bug-NNN.md`, set `status: fixed` and append a one-line
     `verified_fixed: <today> (auto-script N/N green + live-corroborated; advanced <KEY>
     through <hops> to Done)` note to the frontmatter — or, if the advance stopped short,
     `... advanced <KEY> to <last status reached>, blocked at <next hop>` so the file reflects
     reality.
   - Note the `ci/known-failures.json` **candidate-resolved** step (CLAUDE.md CI-triage §4): the
     entry can be removed once it stays green across CI runs. Recommend it; don't delete blindly
     here — leave registry pruning to `/ci`, which sees the whole build.

---

## Phase 4 — Post the result to Teams (skip if `--no-teams`)

```bash
python3 ci/teams.py \
  --status <fixed|reproduces|inconclusive> \
  --bug "<KEY>" \
  --system "<APP-A|APP-B|…>" \
  --build "<build # if known, else omit>" \
  --title "<concise symptom>" \
  --summary "<one or two plain sentences: what you checked (auto-script Class#method N/N, or live) and what you found>" \
  --url "<JIRA_BASE>/browse/<KEY>"
```
Map a "flaky / not-stable" outcome to `--status inconclusive`. With `--dry-run`, append
`--dry-run` and print the payload instead of sending. Card color/emoji: red = reproduces,
green = fixed, amber = inconclusive.

---

## Phase 5 — Summary

Print a short report:
- The bug (key + symptom) and the **outcome** (fixed / reproduces / inconclusive / flaky) with
  the method (auto-script `Class#method`, N/N runs — or manual) and any caveat.
- What you wrote back: Jira comment id, attached evidence, **advance result** — the full hop
  list to Done, or the status it stopped at and why (or "recommended: Done" / "not advanced —
  only 1/3 green"), local bug-file update, and the Teams post status — or, in `--dry-run`,
  that nothing was sent.
- If `inconclusive`/`flaky`, state exactly what blocked or destabilized the check so the user
  can unblock it.

**Honesty rule (same as `/ci`):** never claim a bug is fixed — and never advance or close a
ticket — on a single, flaky, or partial pass. An advance-to-Done requires an all-green run
across `--runs` with reruns off. If the environment blocked you, say so plainly and mark it
inconclusive. If the advance itself stops short of Done (a hop has no matching transition),
say exactly where it stopped — don't imply the ticket reached Done when it didn't.
QA_IO_VN_EOF

cat > "commands/ci.md" <<'QA_IO_VN_EOF'
---
description: Pull the latest Jenkins regression report, triage every failure, fix test bugs (verify locally), and return bug summaries for product bugs.
argument-hint: "['x' for extended local full-suite verify] [build number | 'last'] (both optional)"
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---

# Fix CI Failures — autonomous triage & fix workflow

*Bash snippets below show the reference stack (Java + Maven + JUnit 5 + Playwright-Java).
Substitute your stack's equivalent commands — see `WORKFLOW.md` §6, "Stack adapter" — the
FIX-FIRST triage logic and the bucket definitions are what to keep.*

You are running the CI-failure-fixing workflow for this Playwright test-automation
repo against Jenkins job `regression/main` at `https://jenkins.example.com`.

Credentials live in `.claude/jenkins.env` (gitignored). Never print the token, never
commit it, never hardcode it into any file.

## Execution rules (apply to EVERY command in this workflow)

These are global and non-negotiable for all phases below:

1. **Headless always.** Every `mvn test` invocation MUST include `-Dheadless=true`.
   Never launch a headed browser — no exceptions, in any phase, including single-method
   verifies, the 3× stability loop, and the full-suite run.
2. **Run tests in the background.** Every `mvn test` invocation (and any other
   long-running command — the full-suite run, the 3× loop, a Jenkins `wait`) MUST be
   launched with `run_in_background: true` so it does not block the session; the harness
   re-invokes you when it exits. Do NOT run a test in the foreground and do NOT
   foreground-`sleep`/poll waiting on it.
   - Redirect output to a log file (e.g. `>/tmp/ci_run.log 2>&1`) and, once the
     background command finishes, read that log + `target/surefire-reports/*.txt` to
     judge pass/fail. Only move on after the run has actually completed.
   - For the 3× loop, either launch the iterations as background runs and collect each
     result, or run the whole loop as a single background job that writes per-iteration
     logs — never block the foreground on it.
3. Lightweight, fast commands (git status, reading reports, `jenkins_failures.py`,
   `spotless:apply`) may run in the foreground.

## Argument parsing (do this first)

Raw arguments: `$ARGUMENTS`

Parse them into a **mode** and a **build number**:

- If the first whitespace-separated token is `x` (or `X`) → **EXTENDED mode = ON**, and
  the build number is the *second* token (may be empty → latest completed build).
- Otherwise → **EXTENDED mode = OFF** (plain `/ci`), and the build number is the *first*
  token (may be empty → latest completed build).

Call the resulting build number `BUILD` (it may be empty). **Never pass the literal `x`
to `jenkins_failures.py`** — pass only `BUILD`.

**Neither mode ever commits, pushes, or triggers a Jenkins/CI-CD run.** All
verification is local-only. The difference between the two modes is only how thorough
the local verification is.

- **EXTENDED mode OFF** (`/ci`, `/ci 123`): run Phases 1–5 and STOP. The Phase 3.5 3×
  local stability gate is optional/best-effort here.
- **EXTENDED mode ON** (`/ci x`, `/ci x 123`): run Phases 1–5 **and then** Phase 6 —
  a **full local suite verification**. In this mode:
  - the Phase 3.5 3× local stability gate is **mandatory** — every test you fixed must
    be green ×3 locally before you move on; and
  - after the fixed tests are stable, you run the **entire suite locally** (except the
    known-bug classes) to confirm everything still passes. If that run surfaces **more
    bugs**, fix them (Phase 3/3.5 rules) and re-verify until the suite is green except
    for the documented known bugs.
  - **Still no commit, push, or CI/CD trigger** — Phase 6 is a local gate, not a deploy.

Work through the phases below **in order**. Use a TodoWrite list to track them.

---

## Phase 1 — Fetch the latest report

Run the parser (downloads the Allure results subtree, dedupes reruns, writes a
machine-readable report):

```bash
# Pass only the parsed BUILD (never the mode token 'x').
# Empty BUILD -> the script defaults to the last completed build.
python3 .claude/scripts/jenkins_failures.py $BUILD
```

This writes:
- `.claude/ci-report/failures.json` — `{build, result, failures:[{fullName,class,method,status,message,trace}]}`
- `.claude/ci-report/<fullName>.txt` — full stack trace per failing test

Read `failures.json`. If `failures` is empty → report "Build #N is green, nothing to
fix" and STOP. Otherwise list the failing tests to the user before you start.

A test is only reported as failing if it **never passed across reruns** — so anything
here is a real, reproducible failure, not a one-off flake the rerun already absorbed.

---

## Phase 2 — Triage each failure (FIX-FIRST — the registry is a prior, not a verdict)

**Default to trying to RESOLVE each failure this build.** A prior classification — in
project memory or `ci/known-failures.json` — is a **hint about what to check first, never a
reason to skip a failure or to leave it red unexamined.** Classifications go stale: a UI
redesign can turn a long-standing "product bug" into a fixable test bug, and a backend
that was 500-ing can recover. **Trusting a stale "leave failing" label forever
is the exact failure mode this phase exists to prevent — an infinite loop of wrong
information. Re-confirm before you defer.**

For EACH failing test, in this order:

1. **Read its `.txt` trace and attempt to reproduce / resolve it on its own merits FIRST,
   before you look up any prior label.** Decide what the trace actually shows *this* build:
   - Looks like a **test / UI / selector / wait / data bug** (assertion mismatch, element
     not found, stale selector, race, "broke after a UI change") → **Bucket A: fix it**
     (Phase 3). This is where stale "product bug" labels most often unmask — a redesign moved
     the UI and the test just needs updating. When behavior is unclear, **inspect the live UI
     with the Playwright MCP browser tools** (per CLAUDE.md) — do not guess.
   - Looks like a **backend / app error** (5xx, broken contract) → **re-confirm it still
     reproduces LIVE this build** with the cheapest probe that proves it: `curl` the endpoint,
     or run the single mapped test headless once. Only if it *still* genuinely fails the same
     way is it **Bucket B** (Phase 4). A backend that has recovered → the test is resolved,
     not a bug.
   - Looks like **infra / environment** (service 503/down, cold-boot/callback timeout, missing
     seed) → **Bucket C**; fix it if the fix belongs in the test (self-seed, resilient wait),
     otherwise report environmental.

2. **THEN reconcile with the prior** (project memory + `ci/known-failures.json`,
   via `python3 ci/triage.py`). Use it only to (a) reuse an already-filed bug's `bug-NNN`/Jira
   key instead of duplicating it, and (b) sanity-check your conclusion. Compare your trace to
   the prior's **signature**:
   - **Same signature, still reproduces** (backend still 5xx / same cold-boot timeout) → keep
     the classification. You've now *cheaply re-verified* it — no deep re-diagnosis needed.
   - **Now passes** (mapped test green / endpoint healthy) → **candidate-resolved**: do not
     leave it red. Confirm it stays green and remove its `ci/known-failures.json` entry.
   - **Different signature, or now fixable** (a "product bug" that is now a stale selector; a
     "flake" that now fails on an assertion, not a timeout) → the prior is **STALE**. Do NOT
     defer to it — escalate to a full fix attempt (Phase 3) and re-classify. Update the
     registry entry to the new reality so the wrong label cannot loop again.

**Cost guard** (so fix-first does not re-diagnose everything from scratch every run):
- **Product bugs** — re-verify with a *cheap live probe* (curl / one mapped-test run), not a
  full re-investigation, unless the signature changed. Your registry will accumulate a
  handful of documented backend bugs to expect each build (e.g. a known 500-ing command
  endpoint, a service that returns 503) — probe those, don't re-diagnose them.
- **Flakes** (env/timing: an unpaginated heavy grid, a mid-test token-refresh reload, a
  cold SPA boot per browser context, an SSO callback bounce) are inherently
  unstable — re-running locally just re-flakes and proves nothing. Re-verify them by
  **trace-signature match**, not by chasing a green run; but if the signature *changed*,
  investigate.
- **Test bugs are always ours to fix** — never leave one red because it is "known".

Whatever you re-verify, **record that you re-checked it against THIS build** (`python3
ci/triage.py --update` refreshes `last_seen` / occurrence counts) so the registry reflects a
fresh confirmation, not a months-old guess.

The CI already excludes a known-product-bug shard (e.g. a `KNOWN_BUG_CLASSES` list in
your Jenkinsfile). If a NEW product bug is confirmed, mention it as a candidate
for that list in your summary — but do not edit the Jenkinsfile yourself unless asked.

---

## Phase 3 — Fix test bugs (bucket A / fixable C)

Follow **all** rules in `CLAUDE.md` (POM conventions, no magic strings, fluent API,
`BasePage` waits — never `waitForTimeout`, Allure `@Step`, logging, etc.). When editing
a `*Page.java` Page Object, your Page Object clean-code rules apply (extract hardcoded
domain values into named constants).

For each fix:
1. Make the smallest correct change rooted in the trace evidence (not guesswork).
2. Run `mvn spotless:apply` on touched files.
3. **Verify locally** with reruns disabled so a pass is real, not a retry artifact.
   Run it headless and in the background (`run_in_background: true`); read the log once
   it finishes:

   ```bash
   mvn test -Dtest='ClassName#methodName' -Dheadless=true \
     -Dsurefire.rerunFailingTestsCount=0 -q >/tmp/ci_verify.log 2>&1
   ```

   For a whole class: `-Dtest='ClassName'`. For several: comma-separate.
4. The fix is only "done" when that local run is **green**. If it still fails, read the
   new trace and iterate — do not move on with a red test.

Group related failures (e.g. five failures in one report class that all say "Dashboard
not loaded within 120s" share one root cause — fix once, verify the class).

---

## Phase 3.5 — Stability hardening (make fixed/flaky cases run as stable as possible)

> In **EXTENDED mode (`/ci x`)** the "green ×3" outcome of this phase is a **hard gate**:
> no fix is considered done, and you do not proceed to the Phase 6 full-suite run, until
> every fixed test passes 3/3 here.

A single green run is **not** proof of stability — an unpaginated data grid, a cold
SSO/OTP login, and per-test `BrowserContext` cold-boots all flake intermittently.
For every Bucket-A/fixable-C test you touch, go past the fix and harden it:

1. **Repeat-run to expose flakes.** Run the test(s) **3 times back-to-back**, reruns
   disabled, and record pass/fail per iteration:

   Launch this as a **single background job** (`run_in_background: true`) — headless,
   reruns disabled — and read the per-iteration logs once it finishes. Never run it in
   the foreground.

   ```bash
   for i in 1 2 3; do
     echo "== iter $i =="
     mvn test -Dtest='ClassName#method,...' -Dheadless=true \
       -Dsurefire.rerunFailingTestsCount=0 -q >/tmp/ci_stab_$i.log 2>&1; echo "exit=$?"
     grep -h "Tests run:" target/surefire-reports/<class>.txt
   done
   ```
   Each fresh `mvn` invocation is a **cold** login + cold context — exactly the flake
   surface CI hits. A pass isn't "stable" until it's green across all 3.

2. **Triage every iteration failure by its OWN trace** — it is often a *different* root
   cause than the original CI failure (e.g. the fix lands, but iteration 1 dies in
   `setUp` at `fill("#username")` = cold-login flake, not the test logic). Fix the new
   root cause too; don't dismiss it as "just a flake."

3. **Prefer root-cause hardening over masking.** Apply the right durable pattern:
   - Scope selectors to the row/element that actually carries the target control
     (e.g. `.filter(setHas(detailBtn))`), never `.first()` on a status-mixed grid.
   - Use a generous named wait budget (e.g. `LONG_WAIT_MS`) + `scrollIntoViewIfNeeded()`
     for controls in a wide or un-virtualized grid; never raw `isVisible()`/`innerText()`
     on the full table.
   - Make shared setup resilient (re-navigate-once guards, best-effort waits) when the
     fix belongs in the test layer — but keep it **additive** (happy path unchanged) and
     mindful of blast radius across other suites.
   - **Never** `waitForTimeout`; **never** bump `rerunFailingTestsCount` to hide a flake.
   - Re-run the 3× loop after hardening; iterate until green ×3.

4. **Be honest about residual flakiness.** If a cause is genuinely environmental
   (SSO/backend slowness, shared-env data) and your hardening is best-effort rather
   than a guarantee, say so in the final report with the iteration evidence (e.g. "5/6 →
   3/3 after the guard; can't guarantee 100% — depends on SSO responsiveness").

---

## Phase 4 — Jira-ready bug tickets for product bugs (bucket B)

For every confirmed product bug, produce a professional, **ISTQB-aligned** defect report
the user can paste straight into Jira. **Change no code** for these. One ticket per bug,
using the exact structure below. Fill every field — if a field genuinely doesn't apply,
write `N/A — <why>`, never leave it blank or invent content.

**Persist AND print.** Write every ticket for this build to
`.claude/ci-report/bug-tickets.md` (overwrite the file each run so it always reflects the
latest build), then ALSO paste the tickets back in the chat in Phase 5. The file is a
local artifact (`.claude/ci-report/` is gitignored — never commit it). Structure the file:

```
# CI Bug Tickets — Build #<n>

- Job: regression/main — https://jenkins.example.com/job/regression/job/main/<n>/
- Generated: <today>
- Product bugs (Bucket B): <count> — leave failing, file in Jira.

---

<ticket 1>

---

<ticket 2>
```

If a build has **zero** confirmed product bugs, still write the file with the header and
`- Product bugs (Bucket B): 0 — none this build.` so a stale prior file is never mistaken
for the current result.

**One file per bug (for `/bug`).** After `bug-tickets.md` is finalized, each confirmed
product bug is also split into its own tracked file `bugs/bug-NNN.md` (frontmatter +
full ticket body) by `ci/bugs_split.py`. This runs **automatically** — a PostToolUse hook
in `.claude/settings.json` fires it whenever this workflow writes `bug-tickets.md` (same
hook that regenerates `ci/active-bugs.html`), so you do NOT need to run it by hand. If you
ever need to force it:

```bash
python3 ci/bugs_split.py        # reads .claude/ci-report/bug-tickets.md -> bugs/bug-NNN.md
```

The split is **idempotent by source test**: the same failing test always maps to the same
`bug-NNN` id, and any Jira-logging state already written by `/bug` (`status: logged`,
`jira_key`, …) is preserved across re-runs — `/ci` never un-logs or renumbers a bug you
already filed. Logging these bugs into Jira (current active sprint, "To Do", priority) is
the separate **`/bug`** command; do NOT create Jira issues from `/ci`.

**The active-bug dashboard regenerates automatically.** A PostToolUse hook in
`.claude/settings.json` runs `ci/bug_index.py` whenever this workflow runs
`jenkins_failures.py` (Phase 1) or writes `bug-tickets.md` (Phase 4), so
`ci/active-bugs.html` always reflects the current build — you do NOT need to run it by
hand. If you ever need to force it:

```bash
python3 ci/bug_index.py        # reads .claude/ci-report/{failures.json,bug-tickets.md}
                               # -> ci/active-bugs.html (open in a browser)
```

It groups every failure in the latest build by classification (product bug / no-ticket
test-fix), with severity, priority, reproducibility, and a click-to-expand FULL bug
report (environment, preconditions, steps to reproduce, expected/actual, evidence,
source test, tracking) plus a collapsible stack trace. Purely presentational — it never
re-triages or changes a classification; it reflects whatever `/ci` already wrote.
Mention the path (`ci/active-bugs.html`) in the Phase 5 report.

**Screenshot — attach a real image.** Save an actual screenshot of the failure (or of
the broken screen/state you confirmed in Phase 2) as a PNG to
`.claude/ci-report/<fullName>.png` — where `<fullName>` is the test's fully-qualified
name exactly as it appears in `failures.json` (e.g.
`.claude/ci-report/com.yourco.automation.appa.orders.OrderCrudTest.testCreateOrderPersists.png`).
The bug dashboard embeds that file automatically. Keep the **Screenshot** field text
short — `Failure screenshot from the run (attached).`. If you genuinely cannot capture
one, write `Screenshot: N/A — <why>` and the dashboard simply omits the image. Do NOT
name any capture tool in the ticket text — the report is read by Dev, BA, PO and Team
Lead and must stay tool-agnostic.

**Severity** = technical impact of the defect on the system (set by the tester),
independent of how often it occurs:

| Severity | Meaning |
|---|---|
| Blocker | Core flow unusable, no workaround, blocks further testing |
| Critical | Major feature broken / data loss / 5xx on a primary action |
| Major | Important feature broken but a workaround exists |
| Minor | Limited or partly-cosmetic functional issue, easy workaround |
| Trivial | Cosmetic only (label, alignment, copy) |

**Priority** = business urgency / order to fix (set independently of Severity — a
high-severity bug can be low priority and vice-versa):

| Priority | Meaning |
|---|---|
| P1 – Highest | Fix immediately; blocks a release or the regression suite |
| P2 – High | Fix this sprint |
| P3 – Medium | Schedule in the normal backlog |
| P4 – Low | Fix when convenient |

Ticket template (one per confirmed product bug). It is read by **Dev, BA, PO and Team
Lead** — write in plain language and use **no test-automation jargon** (no tool names, no
internal helper/class names in the reader-facing fields). Keep all technical detail in the
single, clearly-labelled **Technical notes (for Dev)** line — do NOT add separate
"Evidence" / "Suspected area" lines (that was redundant; fold them in here).

**Structure: reader-facing block on top, details below.** Lead with the plain-English
report a non-technical reader needs first — a one/two-sentence summary, then Environment,
Steps to Reproduce, Actual Result, Expected Result. Put the ISTQB metadata and the Dev
technical detail *below* the `———` separator. Two hard rules so the tooling keeps working:
- Every field label MUST be bold **and end with a colon** — `**Steps to Reproduce:**`, not
  `**Steps to Reproduce**`. The dashboard only renders a block as a section when the label
  has a trailing colon; the Jira export then strips the bold so it reads as a clean heading.
- Use the em-dash rule `———` as the on-top/below separator — **never** a `---` line. Bug
  tickets are concatenated with `\n---\n`, so a literal `---` inside a body splits one bug
  into two and drops its metadata.

```
### 🐛 [<System>] <Feature> — <concise symptom>        ← use as the tracker title

<!-- map: <fullName> -->        ← hidden test↔ticket link (parsed for screenshot/section
                                   mapping; never shown to readers). Keep the FQN accurate.

<1–2 plain sentences a non-technical reader understands: what the user did, what went wrong,
and why it matters. This lead paragraph — no label — is the dashboard card description and
the first thing shown in Jira.>

**Environment:** <system> test environment · regression build #<n> · Chromium · SSO login

**Steps to Reproduce:**
1. <user-level action that matches the real flow the test performs — verify against the
   test source; do NOT include test-internal details like poll budgets/timeouts>
2. ...

**Actual Result:**
- <what happens> — <HTTP status / error text / on-screen message>

**Expected Result:**
- <what should happen>

———

**Issue type:** Bug
**System:** APP-A | APP-B | …
**Feature / Component:** <e.g. Orders — Create Order>
**Severity:** <Blocker|Critical|Major|Minor|Trivial> — <one-line justification>
**Priority:** <P1–Highest|P2–High|P3–Medium|P4–Low> — <one-line justification>
**Reproducibility:** Always | Intermittent (<which cases>) | Once

**Preconditions:**
- <state/data needed before the steps — seeded rows, equipment present, etc.>

**Technical notes (for Dev):**
- <root cause + evidence in ONE place: endpoint, payload/type mismatch, status code,
  suspected layer/component. This replaces the old Evidence + Suspected area fields.>

**Business impact:**
- <who is blocked and how badly, in business terms>

**Screenshot:**
- Failure screenshot from the run (attached).   ← save the PNG per the rule above

**Test reference:**
- `<fullName>` — <readable feature + case name> (<file>:<line>)
**Known-failure tracking:** <ci/known-failures.json entry / prior bug id, if registered>
```

The dashboard (`ci/active-bugs.html`) renders **only confirmed bugs** from these tickets:
failures without a bug report, and anything already fixed, are hidden. So every failure
you classify as a real product bug **must** get a ticket here, or it won't appear.

---

## Phase 5 — Final report

Print a single summary table back to the user:

| Test | Bucket | Action taken | Local verify | Stability (3×) |
|---|---|---|---|---|
| ... | A/B/C | Fixed: <what> / Bug ticket / Env | ✅ green / n/a | 3/3 green / n/a |

Then:
- List the files changed (so the user can review the diff).
- Paste all Phase-4 Jira-ready bug tickets **in the chat**, and state that the same
  tickets were written to `.claude/ci-report/bug-tickets.md` (give the path so the user
  can open/copy it). Always do both — persist to the file AND print here.
- Note that each product bug was also split into `bugs/bug-NNN.md`, and the user can file
  them into Jira (active sprint, "To Do", priority) with **`/bug`** (`/bug --dry-run` to
  preview first). Do NOT create Jira issues from `/ci` yourself.
- **EXTENDED mode OFF:** **Do NOT commit, push, or trigger a Jenkins run** unless the
  user explicitly asks. Verification is local-only per the agreed workflow. End by
  telling the user the fixed tests pass locally and are ready for them to commit / kick
  a CI run. Run the optional **Phase 7** Teams summary first (only if `.claude/teams.env`
  is configured), then **STOP here.**
- **EXTENDED mode ON:** do NOT stop — continue to Phase 6 (full local suite
  verification). Phase 5's report is the per-failure summary; you will append the
  full-suite result in Phase 6's report. **Still no commit, push, or CI/CD run.**

Honesty rule: if a fix is a symptom-patch rather than a root-cause cure, say so. If a
test could not be verified locally (needs the live env / a service that's down), say
that plainly instead of claiming green.

---

## Phase 6 — Full local suite verification (EXTENDED mode `/ci x` ONLY)

Skip this entire phase in plain `/ci`. Run it only when EXTENDED mode is ON.
**This phase does NOT commit, push, or trigger any Jenkins/CI-CD run — it is a local
gate only.**

**Precondition gate.** Do NOT proceed unless **every** Bucket-A / fixable-C test you
touched is **green ×3** in the Phase 3.5 loop. If any is not, stop and report — moving
on with an unstable fix defeats the purpose. Bucket-B product bugs and unfixable
environmental cases do not block this phase (they were never expected to pass).

### 6.1 — Run the whole suite locally (minus the known-bug classes)

Run the full local suite with reruns disabled (honest first-pass signal — no retries
hiding a still-flaky fix), excluding the documented known-bug classes so the run isn't
polluted by failures you already triaged as Bucket B / known infra. This run is long —
launch it with `run_in_background: true` (headless) and read the log +
`target/surefire-reports/*.txt` once it completes; never block the foreground on it:

```bash
# Known-bug classes to exclude (keep in sync with the KNOWN_BUG_CLASSES list in
# your Jenkinsfile and the registry). Adjust the list to the
# confirmed-known-bug tests for THIS build.
mvn test -Dheadless=true -Dsurefire.rerunFailingTestsCount=0 \
  -Dtest='!KnownBugFlowTest,!KnownBugApiTest' -q \
  2>&1 | tail -60
```

Use the actual known-bug class names you confirmed in Phase 2 for the exclusion list —
do not blindly copy the example above. Bucket-B / known-infra tests stay excluded; every
other test must pass.

### 6.2 — Triage any new failures, fix, and re-verify

For each failure the full-suite run surfaces that is **not** one of the excluded
known bugs:

1. Read its `target/surefire-reports/*.txt` trace.
2. Classify it (Phase 2 buckets). If it's a **new product bug**, add a Phase-4 bug ticket
   and leave it failing (note it as a known-bug-list candidate). If it's a
   **test bug / fixable env flake (Bucket A/C)**, fix it under the Phase 3/3.5 rules and
   harden it to green ×3.
3. Re-run the affected tests, then re-run the full suite, until the only remaining
   failures are documented known bugs.

Iterate Phases 3 → 3.5 → 6 as needed. Do **not** claim the suite is green while an
undocumented failure remains.

### Final extended report

Append a full-suite-result column to the Phase 5 table and state the local suite outcome:

| Test | Bucket | Fix | Local 3× | Full local suite |
|---|---|---|---|---|
| ... | A | ... | 3/3 green | ✅ passed / ❌ still failing |

End with a one-line verdict: which fixed tests are confirmed green locally (including in
the full-suite run), and any caveats (known product bugs still red, environmental flake,
etc.). **Do NOT commit, push, or trigger a Jenkins run** — leave the working tree for the
user to review and commit themselves. Then run the optional **Phase 7** Teams summary
below (if configured).

---

## Phase 7 — Post the build summary to Teams (optional, both modes, best-effort)

Run this **only if** `.claude/teams.env` exists and `TEAMS_WORKFLOW_URL` is set —
otherwise skip silently (most local runs won't have it). This is a notification only: it
**never** commits, pushes, triggers Jenkins, or changes a classification. A failure to
post must NOT fail the run — report it and move on.

Post one Adaptive Card summarizing this build's result (the same product-bug counts you
reported in Phase 5):

```bash
python3 ci/teams.py \
  --status inconclusive \
  --title "CI triage — regression/main #<BUILD>" \
  --bug "build #<BUILD>" \
  --summary "<N> product bug(s) (leave failing), <M> test bug(s) fixed locally, <K> env/flake. Tickets: .claude/ci-report/bug-tickets.md · dashboard: ci/active-bugs.html"
```

Guidance:
- `--status fixed` when the build is green (no product bugs and all fixes verified),
  `--status reproduces` when confirmed product bugs remain, else `--status inconclusive`.
- Keep `--summary` to the headline counts and the two artifact paths — the detail already
  lives in `bug-tickets.md` and the dashboard; don't paste full tickets into the channel.
- To preview without sending, append `--dry-run`.
- This posts a build summary; per-bug manual re-verification (with screenshot + Jira
  write-back) is the separate `/verify-bug` command.
QA_IO_VN_EOF

cat > "commands/bug.md" <<'QA_IO_VN_EOF'
---
description: Log CI product bugs (bugs/bug-NNN.md, written by /ci) into Jira — into the current active sprint, at "To Do", carrying each ticket's priority. Default logs every un-logged bug (preview then confirm).
argument-hint: "[bug-001 bug-003 ... | (none = all un-logged)] [--dry-run] [--force] [--no-sprint] [--sprint-name \"...\"] [--priority Name] [--status \"To Do\"] [--project KEY]"
allowed-tools: Bash, Read, Edit, Glob, Grep
---

# Log CI product bugs into Jira

You file the confirmed product bugs that `/ci` split into `bugs/bug-NNN.md` as Jira Bug
issues, then mark each bug file as logged so it is never double-filed.

- The bug files come from `/ci` Phase 4 → `ci/bugs_split.py`. Each carries frontmatter
  (`id`, `source_test`, `title`, `system`, `severity`, `priority`, `status`, `jira_key`, …)
  plus the full ISTQB ticket body. `bugs/` is the source of truth here — this command does
  **not** re-run triage.
- `ci/bug_log.py` does the work (creates the issue, adds it to the active sprint, moves it
  to "To Do", writes the Jira key back into the file). `ci/jira.py` is the Jira REST client.
- Creating Jira issues is **outward-facing and hard to undo**. Invoking `/bug` authorizes
  the creation, but per the agreed workflow you **preview the plan and get an explicit OK
  before creating** (except `--dry-run`, which never creates).

Credentials live in gitignored `.claude/jira.env` (`JIRA_BASE` — e.g.
`https://your-org.atlassian.net` — `JIRA_EMAIL`, `JIRA_TOKEN`, `JIRA_PROJECT`). If a
command errors with **"Missing required key … JIRA_TOKEN"** or **"No … JIRA_PROJECT"**,
the env file isn't filled in — tell the user to copy `ci/jira.env.example` →
`.claude/jira.env` and fill it (see `ci/INTEGRATIONS.md`), then stop.
Never invent credentials.

## Argument parsing (do this first)

Raw arguments: `$ARGUMENTS`

- **Bug ids** = every non-flag token that looks like `bug-001`, `bug-1`, `001`, or `1`
  (they are normalized to `bug-NNN`). **No ids → target every un-logged bug** (the default).
- **Flags** (pass straight through to `bug_log.py log`):
  - `--dry-run` — resolve the active sprint + print the plan, create nothing.
  - `--force` — re-file a bug even if it already has a `jira_key`.
  - `--no-sprint` — don't add the issues to any sprint.
  - `--sprint-name "…"` — narrow the active-sprint lookup to a board/sprint containing this.
  - `--priority Name` — override the mapped priority for every issue (e.g. `Medium`).
  - `--status "Name"` — status to land on (default `To Do`).
  - `--project KEY` — override `JIRA_PROJECT` for this run.

Default behavior (no ids, no flags): file **all** un-logged bugs. Already-logged bugs are
always skipped (idempotent) unless `--force` is given.

---

## Phase 1 — Show what will be logged (always)

Run the preview. It is read-only: it resolves the current active sprint and prints one row
per bug that would be created (already-logged bugs are shown as skipped).

```bash
# with explicit ids:
python3 ci/bug_log.py log <ids...> --dry-run <passthrough-flags>
# default (all un-logged):
python3 ci/bug_log.py log --all --dry-run <passthrough-flags>
```

If there are **no bug files** (`bugs/` empty), tell the user to run `/ci` first (it writes
the tickets that get split into `bugs/`), and stop. If every selected bug is already logged,
say so and stop (nothing to do).

Restate the plan to the user in one line: how many issues, into which project + active
sprint, at what status/priority.

---

## Phase 2 — Confirm, then create (skip entirely if `--dry-run`)

If the user passed `--dry-run`, you are done after Phase 1 — report the plan and stop.

Otherwise **ask the user to confirm** the plan from Phase 1 before creating anything (this
is the "preview then confirm" gate; it protects an irreversible external action). Only after
an explicit go-ahead, run the real create — note the required `--yes`:

```bash
python3 ci/bug_log.py log <ids... | --all> --yes <passthrough-flags>
```

For each bug this: creates a Jira **Bug** (summary = ticket title, description = the ticket
body, labels `ci-triage` + `automation` + the bug's system, e.g. `app-a`), adds it to the
active sprint, moves it to `To Do`, and writes `status: logged`, `jira_key`, `jira_url`,
`jira_logged_at`, `jira_sprint` back into `bugs/bug-NNN.md`. A per-bug failure is reported
and does not abort the rest.

---

## Phase 3 — Report

Print a short summary:
- One line per bug: `bug-NNN → <PROJ-123>  <url>` (or the skip/fail reason).
- The sprint the issues landed in and the status they were set to.
- Confirm the bug files were updated to `status: logged` (so a later `/bug` won't re-file
  them, and `/ci` will preserve the link on its next run).

Honesty rule: if any issue couldn't get its priority/sprint/status set (Jira screen or
workflow restrictions), say so plainly with the note `bug_log.py` printed — don't claim a
clean file when a field silently didn't apply.
QA_IO_VN_EOF

cat > "commands/report.md" <<'QA_IO_VN_EOF'
---
description: Generate a plain-English Weekly Test Automation Report from the git history for a date window (default: last completed Mon–Sun week).
argument-hint: "[ last week (default) | this week | last N weeks | last N days | YYYY-MM | YYYY-MM-DD..YYYY-MM-DD ] [--to \"Name\"] [--no-greeting]"
allowed-tools: Bash, Read
---

# Weekly Test Automation Report

Produce a short, business-friendly report of what **you** delivered in a date window,
derived from the git history of this repo. The audience is **your manager**, who wants to
*understand* the week, not read a changelog — plain English, no test jargon, no copy-paste
of commit messages.

The single deliverable is one dense paragraph (~60–115 words) in the established voice.
Everything else below is how you reconstruct the facts behind it.

Raw arguments: `$ARGUMENTS`

---

## Phase 1 — Resolve the date window

Default (no date argument) = the **last completed Monday–Sunday week**. Today is known from
context; compute the previous week's Monday and Sunday. The reports run on a roughly weekly
Mon–Sun cadence (e.g. `Jun 8–14`, `Jun 15–21`).

Argument forms (first matching wins):
- *(empty)* → last completed Mon–Sun week.
- `this week` → this week's Monday → today.
- `last N weeks` → N complete weeks back from the last completed week (a single combined window).
- `last N days` → today minus N days → today.
- `YYYY-MM` (a month) → first to last day of that month; title uses the month name.
- `YYYY-MM-DD..YYYY-MM-DD` → that explicit window.

Flags:
- `--to "Name"` → greet that recipient instead of the default (set your manager's name as
  the default greeting when you adopt this command).
- `--no-greeting` → omit the greeting line; emit only the title + paragraph.

Resolve to two dates `START_DATE` (inclusive) and `END_DATE` (inclusive). State the window
you chose in one line before continuing.

---

## Phase 2 — Gather signal from git (never trust commit messages alone)

Commit messages are often vague (`fix issue`, `add new test cases`), so the report MUST be
reconstructed from the **diff**, not the subjects. Compute the boundary commits and diff
across the whole window:

```bash
# End boundary is exclusive (start of the day AFTER END_DATE)
START=$(git rev-list -1 --before="<START_DATE> 00:00" HEAD)
END=$(git rev-list -1 --before="<END_DATE +1 day> 00:00" HEAD)
git log --oneline $START..$END            # volume / cadence context only
```

Then extract the three things the report is built from:

1. **New coverage — newly added test classes** (these are the headline deliverables):
   ```bash
   git diff --diff-filter=A --name-only $START..$END -- 'src/test/**/*Test.java'
   ```
   For each new file, read its **class-level** `@DisplayName` (the unindented one — format
   `System - Big - Small`) for the feature name, and count its method-level `@DisplayName`
   / `@Test` for the per-feature case count:
   ```bash
   git show $END:<path> | grep -cE '^\s+@Test'          # cases in a new class
   git show $END:<path> | grep -E '@DisplayName'         # names: 1st = feature, rest = cases
   ```

2. **New coverage added to existing classes** — `@Test` blocks added to modified files:
   ```bash
   git diff --diff-filter=M $START..$END -- 'src/test/**/*Test.java' \
     | grep -E '^\+\s*@DisplayName' | sed -E 's/^\+\s*//'
   ```
   Be careful: refactors and moved code inflate raw `+@Test` counts. Only count a method as
   *new coverage* when a new `@DisplayName` test was genuinely added (not reworded/moved).
   When unsure, undercount — honesty over an impressive number.

3. **Stabilization — existing tests/pages touched without adding coverage**:
   ```bash
   git diff --diff-filter=M --name-only $START..$END -- 'src/test/**/*Test.java' \
     'src/main/java/com/yourco/automation/ui/pages/**/*.java'
   ```
   These become the "fixing failures across …" module list. Map each touched file to its
   feature (use the class `@DisplayName` or the file/package name), de-duplicate, and keep
   the human feature names — not class names.

Map package/path → system for grouping and counts (extend this table with one row per
system in your repo):

| Path contains | System label |
|---|---|
| `/appa/` | APP-A |
| `/appb/` | APP-B |
| `/e2e/` | E2E |
| `/api/` | API |
| `/database/` | DB |

Also skim non-test signal that belongs in the report's tail clause when present in the
diff: framework/timeout/retry/nav-wait tuning (`BasePage`, `pom.xml`, `ConfigManager`),
DB/infrastructure renames, removed redundant cases, new Page Objects/helpers, CI fixes.

If the window has **no commits**, say so plainly and stop — do not invent a report.

---

## Phase 3 — Classify & total

- **New cases total** = sum of genuinely-new method-level tests across new + modified
  classes. Report it as the headline number (the examples say "delivered N new automated
  test cases").
- Group new cases by **system → feature** with per-feature counts, e.g.
  `APP-A order recovery workflow (7)`, `APP-B inventory data import (11)`.
- **Stabilization** = the de-duplicated feature list from modified files that didn't add
  coverage. Present as "fixing failures across A, B, C, …".
- Pull product-bug / environment context only if the diff itself shows you
  fixed-or-left-failing a known issue and it's worth one closing sentence (as an earlier
  accepted report did). Don't pad with it otherwise.

---

## Phase 4 — Write the report (match the house style exactly)

Structure, matching the prior weeks verbatim in shape:

```
Hi <recipient>. I give you Weekly Test Automation Report — <Mon D>–<D>, <YYYY>
This week I delivered <N> new automated test cases covering <system + feature (count),
…>, and stabilized the regression suite by fixing failures across <feature, feature, …>
— <optional tail: while tuning global timeouts, retry handling, and navigation waits /
completing the DB rename / removing a redundant case> keeping the suite aligned with the
latest UI changes.
```

Style rules (derived from accepted prior reports and the report owner's feedback):
- **One paragraph, ~60–115 words.** Three lines is fine. Do not exceed ~120 words.
- **Plain English, first person** ("This week I delivered…"). It must be easy for a
  non-engineer to understand.
- **No jargon**: avoid "CRUD", "POM", "E2E vs functional", selector/framework terms.
  Describe coverage by the *user-facing feature* (e.g. "order approval workflow",
  "inventory data import"), not by class name.
- **Lead with the new coverage and its counts**, then the stabilization clause, then the
  optional tail clause, then close with "keeping the suite aligned with the latest UI
  changes" (or a close paraphrase).
- Use an en dash `–` in the date range and `—` for the inline dashes, as in prior weeks.
- If `--no-greeting`, drop the first line and start at "Weekly Test Automation Report — …".
- When the week was stabilization-only (no new cases), open with the fix work instead:
  "This week I focused on stabilizing the regression suite, fixing failures across …".

Optionally add ONE closing sentence only when the diff genuinely supports it (real
remaining failures split into product/back-end defects vs. a test fix you'll do next week),
mirroring earlier accepted reports. Never fabricate counts or defect causes.

---

## Phase 5 — Output

Print, in this order:
1. **Window**: the resolved `START_DATE–END_DATE` and how it was derived.
2. **Basis** (2–4 bullets, for you to sanity-check): new test classes/counts found,
   features stabilized, any tail items (tuning/DB/CI). Keep it terse.
3. **--- REPORT ---** then the final greeting + paragraph, ready to paste into chat.

Honesty rule: the headline count and feature list must trace to the diff you actually
inspected. If you had to estimate (e.g. refactors blurred the new-vs-moved line), say so in
the Basis section and pick the conservative number for the report.
QA_IO_VN_EOF

mkdir -p "toolkit"
cat > "toolkit/INTEGRATIONS.md" <<'QA_IO_VN_EOF'
# Jira + Teams integrations

Local tooling that lets the bug workflow read bugs from **Jira Cloud**, record manual
re-verification results back to them, and post the outcome to a **Teams** channel. Both
connectors are stdlib-only and read credentials from gitignored files under `.claude/`
(the whole `ci/` and `.claude/` trees are gitignored — nothing here is committed).

| File | Role |
|---|---|
| `ci/jira.py` | Jira Cloud REST v3 client: `whoami`, `search`, `get`, `comment`, `transition`, `attach`, `boards`, `sprints`, `create`. |
| `ci/teams.py` | Posts an Adaptive Card to a Teams Power Automate Workflow URL (`--dry-run` to preview). |
| `ci/bugs_split.py` | Splits `/ci`'s `bug-tickets.md` into one tracked `bugs/bug-NNN.md` per product bug (idempotent by source test). |
| `ci/bug_log.py` | Engine behind `/bug`: files `bugs/bug-NNN.md` into Jira (active sprint, "To Do", priority) and writes the key back. |
| `ci/_envfile.py` | Shared `KEY=VALUE` env reader. |
| `.claude/jira.env` | Jira credentials (gitignored). Template: `ci/jira.env.example`. |
| `.claude/teams.env` | Teams workflow URL (gitignored). Template: `ci/teams.env.example`. |
| `/verify-bug` | Command: pull a bug → re-verify live with Playwright MCP → write back to Jira + Teams. |
| `/bug` | Command: log the product bugs `/ci` found (`bugs/bug-NNN.md`) into Jira — active sprint, "To Do", priority. |
| `/ci` Phase 7 | Optional: posts the build's product-bug summary to Teams at the end of a run. |

## 1. Jira Cloud setup

1. Create an API token at <https://id.atlassian.com/manage-profile/security/api-tokens>.
2. Fill `.claude/jira.env`:
   ```
   JIRA_BASE=https://yourcompany.atlassian.net
   JIRA_EMAIL=you@company.com
   JIRA_TOKEN=<the API token>
   JIRA_PROJECT=PROJ                 # optional: default project for `search`
   JIRA_JQL_OPEN=                   # optional: explicit JQL, overrides the project default
   ```
3. Verify:
   ```bash
   python3 ci/jira.py whoami
   python3 ci/jira.py search                 # open bugs (needs JIRA_PROJECT or JIRA_JQL_OPEN)
   python3 ci/jira.py get PROJ-123
   ```

Notes:
- `search` uses the enhanced `/rest/api/3/search/jql` endpoint and falls back to the legacy
  `/rest/api/3/search` if the site hasn't migrated.
- Comments are sent as Atlassian Document Format (ADF); `attach` sends multipart with the
  `X-Atlassian-Token: no-check` header Jira requires.
- `transition --to "Name"` matches by transition **or** target-status name; run
  `transitions <KEY>` first to see what's available from the current status.
- `JIRA_PROJECT` is required for `/bug` (issue creation) and for auto-detecting the active
  sprint — `/bug` finds the project's scrum board and its active sprint from this key alone.

### Creating issues + the `/bug` flow

```bash
python3 ci/jira.py boards                     # Agile boards for JIRA_PROJECT
python3 ci/jira.py sprints                     # the current active sprint
python3 ci/jira.py create --summary "…" --priority High --sprint auto --status "To Do" \
  --labels ci-triage,automation --description-file body.txt
```

- `create` files a Bug (override with `--type`). `--sprint auto` adds it to the project's
  active sprint via the Agile API; `--status` transitions it after creation if it isn't
  already there. Priority is best-effort: if the create screen doesn't expose the priority
  field, the issue is still created and the tool reports that priority wasn't set.
- The `/bug` command drives this per bug and never double-files: a bug whose file already
  has a `jira_key` is skipped unless `--force`. See `.claude/commands/bug.md`.

## 2. Teams setup (Power Automate Workflow — no Azure app registration)

1. In Teams, open the target channel → **…** → **Workflows**.
2. Choose **"Post to a channel when a webhook request is received"** and finish the wizard.
3. Copy the generated HTTPS URL into `.claude/teams.env`:
   ```
   TEAMS_WORKFLOW_URL=https://prod-XX.logic.azure.com:443/workflows/.../invoke?...
   ```
4. Preview without sending, then send a real test card:
   ```bash
   python3 ci/teams.py --text "integration test" --dry-run
   python3 ci/teams.py --status fixed --bug TEST-1 --title "Smoke test" --summary "Hello from ci/teams.py"
   ```

The classic O365 "Incoming Webhook" connector also works if your tenant still allows it
(same payload shape), but Microsoft is retiring it — prefer the Workflow URL.

## 3. Typical flow

```bash
# Re-verify a specific bug end-to-end (live check + Jira write-back + Teams card):
/verify-bug PROJ-123

# Same, and move the issue when confirmed fixed:
/verify-bug PROJ-123 --transition "In Review"

# Read-only rehearsal (verify live, send nothing):
/verify-bug PROJ-123 --dry-run
```
QA_IO_VN_EOF

cat > "toolkit/jira.py" <<'QA_IO_VN_EOF'
#!/usr/bin/env python3
"""Jira Cloud REST v3 client for the bug re-verification workflow (stdlib only).

Pull open bug issues, read one issue, attach a screenshot, add a verification
comment, and transition an issue's status — the pieces /verify-bug needs to
record a manual re-verification back into Jira.

Credentials live in .claude/jira.env (gitignored). Keys:
    JIRA_BASE     https://yourcompany.atlassian.net   (no trailing slash)
    JIRA_EMAIL    you@company.com
    JIRA_TOKEN    API token from id.atlassian.com/manage-profile/security/api-tokens
    JIRA_PROJECT  PROJ                (optional; builds the default open-bug query)
    JIRA_JQL_OPEN optional default JQL for `search` (overrides the project default)

Usage:
    python3 ci/jira.py whoami
    python3 ci/jira.py search [--jql "..."] [--max 20] [--json]
    python3 ci/jira.py get PROJ-123 [--json]
    python3 ci/jira.py comment PROJ-123 --body "text"     # or --body-file f / stdin
    python3 ci/jira.py transitions PROJ-123
    python3 ci/jira.py transition PROJ-123 --to "In Review"
    python3 ci/jira.py attach PROJ-123 --file shot.png

Exit code is non-zero on any Jira/connection error.
"""
import argparse
import base64
import json
import mimetypes
import sys
import urllib.error
import urllib.parse
import urllib.request
import uuid
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from _envfile import load_env, require  # noqa: E402

REPO = Path(__file__).resolve().parent.parent
ENV_FILE = REPO / ".claude" / "jira.env"

# Fields fetched for `get` (description/environment are Atlassian Document Format).
GET_FIELDS = "summary,status,issuetype,priority,description,environment,components,labels"
# Compact fields for `search` listings.
SEARCH_FIELDS = ["summary", "status", "issuetype", "priority", "updated"]


class JiraError(Exception):
    """A Jira API or connection failure, carrying the HTTP status (0 = transport)."""

    def __init__(self, code, message):
        super().__init__(message)
        self.code = code


def client():
    cfg = load_env(ENV_FILE)
    base, email, token = require(cfg, "JIRA_BASE", "JIRA_EMAIL", "JIRA_TOKEN")
    auth = base64.b64encode(f"{email}:{token}".encode()).decode()
    return base.rstrip("/"), auth, cfg


def _request(base, auth, method, path, data=None, headers=None, raw=False):
    """Perform a request and return parsed JSON ({} for an empty 2xx body)."""
    hdrs = {"Authorization": "Basic " + auth, "Accept": "application/json"}
    body = None
    if raw:
        body = data
    elif data is not None:
        body = json.dumps(data).encode()
        hdrs["Content-Type"] = "application/json"
    if headers:
        hdrs.update(headers)
    req = urllib.request.Request(base + path, data=body, headers=hdrs, method=method)
    try:
        with urllib.request.urlopen(req, timeout=45) as resp:
            payload = resp.read()
            if not payload:
                return {}
            try:
                return json.loads(payload)
            except json.JSONDecodeError:
                return {"_raw": payload.decode("utf-8", "replace")}
    except urllib.error.HTTPError as e:
        detail = e.read().decode("utf-8", "replace")
        raise JiraError(e.code, f"{method} {path} -> HTTP {e.code}: {detail}")
    except urllib.error.URLError as e:
        raise JiraError(0, f"{method} {path} -> connection error: {e.reason}")


# ---------------------------------------------------------------------------
# Atlassian Document Format (ADF) helpers — v3 comments/descriptions use ADF.
# ---------------------------------------------------------------------------
def text_to_adf(text):
    """Turn plain text into a minimal ADF doc (blank lines split paragraphs)."""
    content = []
    for block in text.replace("\r\n", "\n").split("\n\n"):
        block = block.strip("\n")
        if not block:
            continue
        nodes = []
        for i, line in enumerate(block.split("\n")):
            if i:
                nodes.append({"type": "hardBreak"})
            if line:
                nodes.append({"type": "text", "text": line})
        if nodes:
            content.append({"type": "paragraph", "content": nodes})
    if not content:
        content = [{"type": "paragraph", "content": [{"type": "text", "text": text or " "}]}]
    return {"type": "doc", "version": 1, "content": content}


def adf_to_text(node):
    """Flatten an ADF node tree to readable plain text (best-effort)."""
    out = []

    def walk(n):
        if isinstance(n, dict):
            t = n.get("type")
            if t == "text":
                out.append(n.get("text", ""))
            elif t == "hardBreak":
                out.append("\n")
            for c in n.get("content", []):
                walk(c)
            if t in ("paragraph", "heading", "listItem", "blockquote", "codeBlock"):
                out.append("\n")
        elif isinstance(n, list):
            for c in n:
                walk(c)

    walk(node)
    return "".join(out).strip()


# ---------------------------------------------------------------------------
# API operations
# ---------------------------------------------------------------------------
def search(base, auth, jql, max_results=20):
    """Run a JQL search. Tries the enhanced /search/jql endpoint, falls back to legacy."""
    try:
        return _request(
            base,
            auth,
            "POST",
            "/rest/api/3/search/jql",
            {"jql": jql, "maxResults": max_results, "fields": SEARCH_FIELDS},
        )
    except JiraError as e:
        if e.code in (400, 404, 405, 410):
            qs = urllib.parse.urlencode(
                {"jql": jql, "maxResults": max_results, "fields": ",".join(SEARCH_FIELDS)}
            )
            return _request(base, auth, "GET", "/rest/api/3/search?" + qs)
        raise


def get_issue(base, auth, key, fields=GET_FIELDS):
    return _request(base, auth, "GET", f"/rest/api/3/issue/{key}?fields={fields}")


def set_description(base, auth, key, text):
    """Replace an issue's description with the given plain text (stored as ADF)."""
    return _request(
        base, auth, "PUT", f"/rest/api/3/issue/{key}",
        {"fields": {"description": text_to_adf(text)}},
    )


def add_comment(base, auth, key, text):
    return _request(
        base, auth, "POST", f"/rest/api/3/issue/{key}/comment", {"body": text_to_adf(text)}
    )


def list_transitions(base, auth, key):
    return _request(base, auth, "GET", f"/rest/api/3/issue/{key}/transitions")


def do_transition(base, auth, key, to_name):
    data = list_transitions(base, auth, key)
    avail = data.get("transitions", [])
    match = None
    for tr in avail:
        names = {tr["name"].lower(), (tr.get("to") or {}).get("name", "").lower()}
        if to_name.lower() in names:
            match = tr
            break
    if not match:
        raise JiraError(
            0,
            f"No transition matching '{to_name}'. Available: "
            + ", ".join(t["name"] for t in avail),
        )
    _request(base, auth, "POST", f"/rest/api/3/issue/{key}/transitions", {"transition": {"id": match["id"]}})
    return match


def add_attachment(base, auth, key, file_path):
    p = Path(file_path)
    if not p.exists():
        raise JiraError(0, f"File not found: {file_path}")
    boundary = "----jira" + uuid.uuid4().hex
    ctype = mimetypes.guess_type(p.name)[0] or "application/octet-stream"
    head = (
        f"--{boundary}\r\n"
        f'Content-Disposition: form-data; name="file"; filename="{p.name}"\r\n'
        f"Content-Type: {ctype}\r\n\r\n"
    ).encode()
    body = head + p.read_bytes() + f"\r\n--{boundary}--\r\n".encode()
    headers = {
        "Content-Type": f"multipart/form-data; boundary={boundary}",
        "X-Atlassian-Token": "no-check",
    }
    return _request(
        base, auth, "POST", f"/rest/api/3/issue/{key}/attachments", data=body, headers=headers, raw=True
    )


# ---------------------------------------------------------------------------
# Issue creation + Agile (board / sprint) helpers — what /bug needs to file a
# CI bug into the current active sprint, at "To Do", with a priority.
# ---------------------------------------------------------------------------
def list_boards(base, auth, project):
    """Return the Agile boards scoped to a project (may be empty)."""
    qs = urllib.parse.urlencode({"projectKeyOrId": project})
    return _request(base, auth, "GET", "/rest/agile/1.0/board?" + qs).get("values", [])


def active_sprint(base, auth, project, board_name=None):
    """Find the current active sprint on the project's board(s).

    Returns the sprint dict ({id, name, ...}) or None. When board_name is given,
    only boards whose name contains it are considered. Scrum boards carry sprints;
    kanban boards 400 on the sprint endpoint and are skipped.
    """
    boards = list_boards(base, auth, project)
    if board_name:
        narrowed = [b for b in boards if board_name.lower() in b.get("name", "").lower()]
        boards = narrowed or boards
    for b in boards:
        try:
            sprints = _request(
                base, auth, "GET", f"/rest/agile/1.0/board/{b['id']}/sprint?state=active"
            ).get("values", [])
        except JiraError:
            continue  # not a scrum board / no sprint support
        if sprints:
            s = dict(sprints[0])
            s["_board"] = b.get("name")
            return s
    return None


def add_to_sprint(base, auth, sprint_id, key):
    """Move an existing issue into a sprint via the Agile API."""
    return _request(
        base, auth, "POST", f"/rest/agile/1.0/sprint/{sprint_id}/issue", {"issues": [key]}
    )


def resolve_account(base, auth, who):
    """Resolve 'me' / an accountId / an email (or display name) to a Jira accountId."""
    if not who:
        return None
    if who.lower() == "me":
        return _request(base, auth, "GET", "/rest/api/3/myself").get("accountId")
    if ":" in who or ("@" not in who and len(who) >= 16):
        return who  # already looks like an accountId
    users = _request(base, auth, "GET", "/rest/api/3/user/search?" + urllib.parse.urlencode({"query": who}))
    for u in users:
        if u.get("emailAddress", "").lower() == who.lower():
            return u.get("accountId")
    if users:
        return users[0].get("accountId")
    raise JiraError(0, f"No Jira user found matching '{who}'")


def add_issue_link(base, auth, link_type, from_key, to_key):
    """Link two issues. from_key is the outward side (e.g. 'Relates' -> 'relates to')."""
    return _request(
        base,
        auth,
        "POST",
        "/rest/api/3/issueLink",
        {"type": {"name": link_type}, "outwardIssue": {"key": from_key}, "inwardIssue": {"key": to_key}},
    )


def current_status(base, auth, key):
    """Return an issue's current status name."""
    return (get_issue(base, auth, key, "status").get("fields", {}).get("status") or {}).get("name", "")


def transition_path(base, auth, key, statuses):
    """Walk an ordered list of target statuses, one direct transition per hop.

    Custom workflows often place a status like 'TO TEST' several hops from the
    initial state, with no single transition to it. The caller supplies the
    ordered waypoints (each must be a direct transition from the previous one);
    a status already reached is skipped. Returns [(status, ok, detail)]; stops at
    the first hop that has no matching transition.
    """
    results = []
    for target in statuses:
        if current_status(base, auth, key).lower() == target.lower():
            results.append((target, True, "already there"))
            continue
        try:
            tr = do_transition(base, auth, key, target)
            results.append((target, True, tr["name"]))
        except JiraError as e:
            results.append((target, False, str(e)))
            break
    return results


def create_issue(base, auth, project, summary, description_text, issuetype="Bug",
                 priority=None, labels=None, assignee=None, reporter=None):
    """Create an issue. Returns (result, priority_set).

    assignee/reporter are Jira accountIds (already resolved). Priority is
    best-effort: if the create screen rejects the priority field (some issue
    types don't expose it, e.g. AutoTask), the create is retried without it and
    priority_set comes back False so the caller can warn.
    """
    fields = {
        "project": {"key": project},
        "issuetype": {"name": issuetype},
        "summary": summary[:254],
        "description": text_to_adf(description_text),
    }
    if labels:
        fields["labels"] = labels
    if priority:
        fields["priority"] = {"name": priority}
    if assignee:
        fields["assignee"] = {"accountId": assignee}
    if reporter:
        fields["reporter"] = {"accountId": reporter}
    try:
        return _request(base, auth, "POST", "/rest/api/3/issue", {"fields": fields}), bool(priority)
    except JiraError as e:
        if priority and e.code == 400 and "priority" in str(e).lower():
            fields.pop("priority", None)
            return _request(base, auth, "POST", "/rest/api/3/issue", {"fields": fields}), False
        raise


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def _read_body(args):
    if args.body is not None:
        return args.body
    if args.body_file:
        return Path(args.body_file).read_text()
    if not sys.stdin.isatty():
        return sys.stdin.read()
    raise SystemExit("Provide --body, --body-file, or pipe the comment text via stdin.")


def _print_issue(it):
    f = it.get("fields", {})
    st = (f.get("status") or {}).get("name", "?")
    typ = (f.get("issuetype") or {}).get("name", "?")
    pri = (f.get("priority") or {}).get("name", "-")
    print(f"{it['key']}  [{typ} | {st} | {pri}]  {f.get('summary','')}")
    desc = adf_to_text(f.get("description"))
    if desc:
        print("\n" + desc)
    env = adf_to_text(f.get("environment"))
    if env:
        print("\nEnvironment:\n" + env)


def main():
    ap = argparse.ArgumentParser(description="Jira Cloud REST v3 client for /verify-bug.")
    sub = ap.add_subparsers(dest="cmd", required=True)

    sub.add_parser("whoami", help="Verify credentials (GET /myself).")

    sp = sub.add_parser("search", help="List issues by JQL (defaults to open bugs).")
    sp.add_argument("--jql")
    sp.add_argument("--max", type=int, default=20)
    sp.add_argument("--json", action="store_true")

    gp = sub.add_parser("get", help="Show one issue.")
    gp.add_argument("key")
    gp.add_argument("--json", action="store_true")

    cp = sub.add_parser("comment", help="Add a comment to an issue.")
    cp.add_argument("key")
    cp.add_argument("--body")
    cp.add_argument("--body-file")

    dp = sub.add_parser("set-description", help="Replace an issue's description.")
    dp.add_argument("key")
    dp.add_argument("--body")
    dp.add_argument("--body-file")

    tlp = sub.add_parser("transitions", help="List available status transitions.")
    tlp.add_argument("key")

    tp = sub.add_parser("transition", help="Move an issue to a status by name.")
    tp.add_argument("key")
    tp.add_argument("--to", required=True)

    apx = sub.add_parser("attach", help="Upload a file as an attachment.")
    apx.add_argument("key")
    apx.add_argument("--file", required=True)

    bp = sub.add_parser("boards", help="List Agile boards for the project.")
    bp.add_argument("--project")

    spr = sub.add_parser("sprints", help="Show the current active sprint for the project.")
    spr.add_argument("--project")
    spr.add_argument("--board-name")

    cr = sub.add_parser("create", help="Create an issue (Bug by default).")
    cr.add_argument("--project")
    cr.add_argument("--summary", required=True)
    cr.add_argument("--description")
    cr.add_argument("--description-file")
    cr.add_argument("--type", default="Bug")
    cr.add_argument("--priority", help="Jira priority NAME, e.g. Highest / High / Medium / Low.")
    cr.add_argument("--labels", help="Comma-separated labels.")
    cr.add_argument(
        "--sprint",
        help="'auto' to add to the project's active sprint, or a numeric sprint id. Omit for none.",
    )
    cr.add_argument("--board-name", help="Narrow active-sprint lookup to a board (with --sprint auto).")
    cr.add_argument("--status", help="Transition the new issue to this status (e.g. 'To Do') if it isn't already.")
    cr.add_argument("--assignee", help="Assign the new issue: 'me', an accountId, or an email.")
    cr.add_argument("--reporter", help="Set the reporter: 'me', an accountId, or an email.")
    cr.add_argument("--json", action="store_true")

    lk = sub.add_parser("link", help="Link two issues (e.g. 'Relates').")
    lk.add_argument("from_key", help="The outward issue key (e.g. the new AutoTask).")
    lk.add_argument("--to", required=True, help="The inward issue key (e.g. the dev ticket).")
    lk.add_argument("--type", default="Relates", help="Link type name (default 'Relates').")

    adv = sub.add_parser("advance", help="Walk an issue through a '>'-delimited status path.")
    adv.add_argument("key")
    adv.add_argument("--path", required=True, help="e.g. 'IN PROGRESS>Code Review>TO DEPLOY>TO TEST'")

    args = ap.parse_args()
    base, auth, cfg = client()

    try:
        if args.cmd == "whoami":
            me = _request(base, auth, "GET", "/rest/api/3/myself")
            print(f"{me.get('displayName')} <{me.get('emailAddress')}>  ({base})")

        elif args.cmd == "search":
            jql = args.jql or cfg.get("JIRA_JQL_OPEN")
            if not jql:
                proj = cfg.get("JIRA_PROJECT")
                if not proj:
                    raise SystemExit("No --jql, JIRA_JQL_OPEN, or JIRA_PROJECT to build a query.")
                jql = f"project = {proj} AND issuetype = Bug AND statusCategory != Done ORDER BY updated DESC"
            issues = search(base, auth, jql, args.max).get("issues", [])
            if args.json:
                print(json.dumps(issues, indent=2))
            elif not issues:
                print("No issues match.")
            else:
                for it in issues:
                    f = it.get("fields", {})
                    st = (f.get("status") or {}).get("name", "?")
                    print(f"{it['key']:<14}{st:<16}{f.get('summary','')}")

        elif args.cmd == "get":
            it = get_issue(base, auth, args.key)
            print(json.dumps(it, indent=2)) if args.json else _print_issue(it)

        elif args.cmd == "comment":
            res = add_comment(base, auth, args.key, _read_body(args))
            print(f"Commented on {args.key} (comment id {res.get('id')}).")

        elif args.cmd == "set-description":
            set_description(base, auth, args.key, _read_body(args))
            print(f"Description replaced on {args.key}.")

        elif args.cmd == "transitions":
            for tr in list_transitions(base, auth, args.key).get("transitions", []):
                print(f"{tr['id']:<6}{tr['name']:<22}-> {(tr.get('to') or {}).get('name','?')}")

        elif args.cmd == "transition":
            tr = do_transition(base, auth, args.key, args.to)
            print(f"Moved {args.key} via '{tr['name']}' -> {(tr.get('to') or {}).get('name','?')}.")

        elif args.cmd == "attach":
            res = add_attachment(base, auth, args.key, args.file)
            names = ", ".join(a.get("filename", "?") for a in res) if isinstance(res, list) else res
            print(f"Attached to {args.key}: {names}")

        elif args.cmd == "boards":
            project = args.project or cfg.get("JIRA_PROJECT")
            if not project:
                raise SystemExit("No --project or JIRA_PROJECT set.")
            boards = list_boards(base, auth, project)
            if not boards:
                print(f"No boards found for project {project}.")
            for b in boards:
                print(f"{b.get('id'):<6}{b.get('type',''):<8}{b.get('name','')}")

        elif args.cmd == "sprints":
            project = args.project or cfg.get("JIRA_PROJECT")
            if not project:
                raise SystemExit("No --project or JIRA_PROJECT set.")
            s = active_sprint(base, auth, project, args.board_name)
            if not s:
                print(f"No active sprint found for project {project}.")
            else:
                print(f"{s.get('id')}  {s.get('name')}  (board: {s.get('_board','?')}, state: {s.get('state','?')})")

        elif args.cmd == "create":
            project = args.project or cfg.get("JIRA_PROJECT")
            if not project:
                raise SystemExit("No --project or JIRA_PROJECT set.")
            desc = args.description
            if desc is None and args.description_file:
                desc = Path(args.description_file).read_text()
            if desc is None and not sys.stdin.isatty():
                desc = sys.stdin.read()
            if desc is None:
                desc = args.summary
            labels = [x.strip() for x in (args.labels or "").split(",") if x.strip()]
            assignee = resolve_account(base, auth, args.assignee) if args.assignee else None
            reporter = resolve_account(base, auth, args.reporter) if args.reporter else None

            # Resolve sprint before creating so a bad --sprint fails fast.
            sprint = None
            if args.sprint:
                if args.sprint.lower() == "auto":
                    sprint = active_sprint(base, auth, project, args.board_name)
                    if not sprint:
                        print(f"Warning: no active sprint for {project} — creating in backlog.", file=sys.stderr)
                elif args.sprint.isdigit():
                    sprint = {"id": int(args.sprint), "name": args.sprint}
                else:
                    raise SystemExit("--sprint must be 'auto' or a numeric sprint id.")

            res, pr_set = create_issue(
                base, auth, project, args.summary, desc, args.type, args.priority, labels,
                assignee, reporter,
            )
            key = res.get("key")
            notes = []
            if args.priority and not pr_set:
                notes.append("priority NOT set (field not on create screen)")
            if sprint:
                try:
                    add_to_sprint(base, auth, sprint["id"], key)
                    notes.append(f"sprint '{sprint.get('name')}'")
                except JiraError as e:
                    notes.append(f"sprint NOT set ({e.code})")
            if args.status:
                waypoints = [s.strip() for s in args.status.split(">") if s.strip()]
                steps = transition_path(base, auth, key, waypoints)
                final = current_status(base, auth, key)
                if steps and steps[-1][1] and final.lower() == waypoints[-1].lower():
                    notes.append(f"status -> {final}")
                else:
                    failed = next((s for s in steps if not s[1]), None)
                    notes.append(
                        f"status left at '{final}'"
                        + (f" (no '{failed[0]}' transition)" if failed else "")
                    )
            if args.json:
                out = {"key": key, "url": f"{base}/browse/{key}", "priority_set": pr_set,
                       "sprint": sprint, "notes": notes}
                print(json.dumps(out, indent=2))
            else:
                tail = ("  [" + "; ".join(notes) + "]") if notes else ""
                print(f"Created {key}  {base}/browse/{key}{tail}")

        elif args.cmd == "link":
            add_issue_link(base, auth, args.type, args.from_key, args.to)
            print(f"Linked {args.from_key} —[{args.type}]→ {args.to}")

        elif args.cmd == "advance":
            waypoints = [s.strip() for s in args.path.split(">") if s.strip()]
            for status, ok, detail in transition_path(base, auth, args.key, waypoints):
                print(f"  {'OK ' if ok else 'FAIL'} {status}  ({detail})")
            print(f"{args.key} now at: {current_status(base, auth, args.key)}")
    except JiraError as e:
        sys.exit(f"Jira error: {e}")


if __name__ == "__main__":
    main()
QA_IO_VN_EOF

cat > "toolkit/teams.py" <<'QA_IO_VN_EOF'
#!/usr/bin/env python3
"""Post a bug-verification / CI-triage result to a Teams channel via a Power Automate Workflow URL.

Microsoft is retiring O365 connector webhooks; the current path is a Teams
"Workflows" flow using the "Send webhook alerts to a channel" (a.k.a. "Post to a
channel when a webhook request is received") trigger, which gives you an HTTPS URL
that accepts an Adaptive Card payload.

Credential lives in .claude/teams.env (gitignored):
    TEAMS_WORKFLOW_URL   https://.../invoke?...&sig=...

Usage:
    python3 ci/teams.py --status reproduces --bug PROJ-123 --system APP-A --build 556 \
        --title "Set Speed never completes" \
        --summary "Confirmed: still hangs in EXECUTING; never reaches Success." \
        --url https://yourco.atlassian.net/browse/PROJ-123
    python3 ci/teams.py --text "Plain status message"
    python3 ci/teams.py --card-file card.json
    # add --dry-run to print the exact payload without sending (no credential needed)

Summary formatting: the --summary text is auto-formatted into scannable bullets.
Separate points with newlines or "; "; a trailing "Tickets: … · dashboard: …"
clause (or any http/… reference) is pulled out and rendered as a subtle footnote.

Extra facts and links (both repeatable, optional):
    --fact "Owner=QA"  --fact "Sprint=43"
    --link "Open build=http://…/714/"  --link "Dashboard=http://…/active-bugs.html"

Exit code is non-zero on a send failure.
"""
import argparse
import datetime as _dt
import json
import sys
import urllib.error
import urllib.request
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from _envfile import load_env  # noqa: E402

REPO = Path(__file__).resolve().parent.parent
ENV_FILE = REPO / ".claude" / "teams.env"

# status -> (emoji, TextBlock color, Container style, human label)
STATUS = {
    "reproduces": ("\U0001F534", "Attention", "attention", "Still reproduces"),
    "fixed": ("\U0001F7E2", "Good", "good", "Cannot reproduce — looks fixed"),
    "inconclusive": ("\U0001F7E1", "Warning", "warning", "Inconclusive"),
}

# Markers that make a summary segment a "reference/link" footnote rather than a bullet.
_REF_MARKERS = ("tickets:", "dashboard:", "docs:", "report:", "link:", "links:", "artifacts:")


def _summary_items(summary):
    """Split a free-text summary into (bullets, reference-lines).

    Points may be separated by newlines or "; ". A trailing reference clause
    ("… . Tickets: x · dashboard: y") is peeled off each point into `refs`.
    """
    raw = (summary or "").strip()
    if not raw:
        return [], []
    if "\n" in raw:
        parts = [p.strip(" \t•-") for p in raw.splitlines() if p.strip()]
    else:
        parts = [p.strip() for p in raw.split("; ") if p.strip()]

    bullets, refs = [], []
    for p in parts:
        low = p.lower()
        # Peel a mid-string reference clause (earliest marker after position 0).
        cut = None
        for m in _REF_MARKERS:
            i = low.find(m)
            if i > 0:
                cut = i if cut is None else min(cut, i)
        if cut is not None:
            head = p[:cut].rstrip(" .·|—-")
            tail = p[cut:].strip()
            if head:
                bullets.append(head)
            if tail:
                refs.append(tail)
        elif any(low.startswith(m) for m in _REF_MARKERS) or low.startswith("http"):
            refs.append(p)
        else:
            bullets.append(p)
    return bullets, refs


def _tb(text, **kw):
    block = {"type": "TextBlock", "wrap": True, "text": text}
    block.update(kw)
    return block


def build_card(args):
    emoji, tcolor, cstyle, label = STATUS.get(
        args.status, ("\U0001F50E", "Accent", "accent", args.status or "Result")
    )

    # 1) Header band — colored container with the title (+ a subtle context subtitle).
    header_items = [_tb(f"{emoji} {args.title or 'Bug verification'}", size="Large", weight="Bolder")]
    subtitle = args.bug or args.system
    if subtitle:
        header_items.append(_tb(subtitle, spacing="None", isSubtle=True))
    header = {"type": "Container", "style": cstyle, "bleed": True, "items": header_items}

    # 2) Prominent result line in the status colour.
    result_line = _tb(f"{emoji} {label}", weight="Bolder", size="Medium", color=tcolor)

    # 3) Facts.
    facts = []
    if args.system:
        facts.append({"title": "System", "value": args.system})
    if args.build:
        facts.append({"title": "Build", "value": str(args.build)})
    if args.bug:
        facts.append({"title": "Reference", "value": args.bug})
    for kv in args.fact or []:
        if "=" in kv:
            k, v = kv.split("=", 1)
            facts.append({"title": k.strip(), "value": v.strip()})
    facts.append({"title": "Generated", "value": _dt.date.today().isoformat()})

    body = [header, result_line, {"type": "FactSet", "facts": facts}]

    # 4) Summary — bullets in a subtle panel, references as small footnotes.
    bullets, refs = _summary_items(args.summary)
    if len(bullets) == 1 and not refs:
        # A single plain paragraph reads better without a lone bullet.
        body.append(
            {
                "type": "Container",
                "style": "emphasis",
                "separator": True,
                "spacing": "Medium",
                "items": [_tb(bullets[0])],
            }
        )
    elif bullets:
        # Keep a leading emoji/symbol as the marker; otherwise add a bullet dot.
        rendered = [
            _tb(b if (b[:1] and not b[:1].isalnum()) else f"• {b}", spacing="Small")
            for b in bullets
        ]
        body.append(
            {
                "type": "Container",
                "style": "emphasis",
                "separator": True,
                "spacing": "Medium",
                "items": rendered,
            }
        )
    if refs:
        body.append(
            {
                "type": "Container",
                "spacing": "Small",
                "items": [_tb(r, size="Small", isSubtle=True, spacing="Small") for r in refs],
            }
        )

    card = {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.4",
        "msteams": {"width": "Full"},
        "body": body,
    }

    # 5) Actions — Jira button (--url) plus any --link "Label=URL".
    actions = []
    if args.url:
        actions.append({"type": "Action.OpenUrl", "title": "Open in Jira", "url": args.url})
    for lk in args.link or []:
        if "=" in lk:
            title, u = lk.split("=", 1)
            actions.append({"type": "Action.OpenUrl", "title": title.strip(), "url": u.strip()})
    if actions:
        card["actions"] = actions
    return card


def text_card(text):
    return {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [_tb(text)],
    }


def envelope(card):
    """Wrap an Adaptive Card in the message shape the Workflow trigger expects."""
    return {
        "type": "message",
        "attachments": [
            {"contentType": "application/vnd.microsoft.card.adaptive", "content": card}
        ],
    }


def post(url, payload):
    data = json.dumps(payload).encode()
    req = urllib.request.Request(
        url, data=data, headers={"Content-Type": "application/json"}, method="POST"
    )
    try:
        with urllib.request.urlopen(req, timeout=30) as resp:
            return resp.status, resp.read().decode("utf-8", "replace")
    except urllib.error.HTTPError as e:
        raise SystemExit(f"Teams post failed: HTTP {e.code}: {e.read().decode('utf-8','replace')}")
    except urllib.error.URLError as e:
        raise SystemExit(f"Teams post failed: connection error: {e.reason}")


def main():
    ap = argparse.ArgumentParser(description="Post a verification / CI-triage result to Teams.")
    ap.add_argument("--status", choices=list(STATUS), help="Verification outcome.")
    ap.add_argument("--title")
    ap.add_argument("--bug", help="Jira key or test name.")
    ap.add_argument("--system")
    ap.add_argument("--build")
    ap.add_argument("--summary", help="Free text; auto-formatted into bullets (split on newlines/'; ').")
    ap.add_argument("--fact", action="append", help="Extra fact 'Title=Value' (repeatable).")
    ap.add_argument("--url", help="Link rendered as an 'Open in Jira' button.")
    ap.add_argument("--link", action="append", help="Extra action button 'Label=URL' (repeatable).")
    ap.add_argument("--text", help="Send a plain message instead of a result card.")
    ap.add_argument("--card-file", help="Send a raw Adaptive Card JSON file (the card content).")
    ap.add_argument("--dry-run", action="store_true", help="Print the payload, do not send.")
    args = ap.parse_args()

    if args.card_file:
        card = json.loads(Path(args.card_file).read_text())
    elif args.text:
        card = text_card(args.text)
    else:
        card = build_card(args)
    payload = envelope(card)

    if args.dry_run:
        print(json.dumps(payload, indent=2))
        return

    cfg = load_env(ENV_FILE)
    url = cfg.get("TEAMS_WORKFLOW_URL")
    if not url:
        sys.exit(f"TEAMS_WORKFLOW_URL missing — set it in {ENV_FILE} (or use --dry-run).")
    status, _ = post(url, payload)
    print(f"Posted to Teams (HTTP {status}).")


if __name__ == "__main__":
    main()
QA_IO_VN_EOF

cat > "toolkit/triage.py" <<'QA_IO_VN_EOF'
#!/usr/bin/env python3
"""Recurrence-aware CI triage.

Pulls a Jenkins build's Allure failures and matches them against
ci/known-failures.json so /ci only has to deep-triage NEW failures.

  python3 ci/triage.py                # triage the latest build (report only)
  python3 ci/triage.py --build 495    # triage a specific build
  python3 ci/triage.py --update       # also persist occurrence/last_seen + add NEW stubs

Exit code is non-zero when there are NEW (untriaged) failures, so automation
can branch on "is there anything a human/AI still needs to look at?".

Credentials are read from .claude/jenkins.env (JENKINS_BASE, JENKINS_JOB,
JENKINS_USER, JENKINS_TOKEN). Stdlib only.
"""
import argparse
import base64
import json
import os
import sys
import urllib.request
from pathlib import Path

REPO = Path(__file__).resolve().parent.parent
REGISTRY = REPO / "ci" / "known-failures.json"
ENV_FILE = REPO / ".claude" / "jenkins.env"

# Substrings in a test's @DisplayName that strongly imply it asserts on the
# PRESENCE of backing data (rows, counts, first-of-list). When the shared env is
# wiped these fail "empty" — they
# are env-data gaps fixable by seeding, NOT product/test bugs. triage.py flags
# NEW failures whose name matches so they aren't deep-triaged from scratch.
# Remediation technique: ci/SEEDING_PLAYBOOK.md.
EMPTY_DATA_HINTS = (
    "at least one",
    "restore the rows",
    "exposes",
    "shows the",
    "filters the table",
    "loads on",
    "loads with",
    "requires a zone",
    "should not be empty",
    "each ",
)


def load_env():
    cfg = {}
    for line in ENV_FILE.read_text().splitlines():
        line = line.strip()
        if not line or line.startswith("#") or "=" not in line:
            continue
        k, v = line.split("=", 1)
        cfg[k.strip()] = v.strip().strip('"').strip("'")
    base = cfg["JENKINS_BASE"] + cfg["JENKINS_JOB"]
    auth = base64.b64encode(
        f"{cfg['JENKINS_USER']}:{cfg['JENKINS_TOKEN']}".encode()
    ).decode()
    return base, auth


def fetch(url, auth):
    req = urllib.request.Request(url, headers={"Authorization": "Basic " + auth})
    return urllib.request.urlopen(req, timeout=45).read()


def latest_build(base, auth):
    info = json.loads(fetch(f"{base}/lastBuild/api/json?tree=number", auth))
    return info["number"]


def collect_failures(base, auth, build):
    """Return list of dicts: {key, cls, test, status, flaky, retries}."""
    suites = json.loads(fetch(f"{base}/{build}/allure/data/suites.json", auth))
    names = {}

    def index(node):
        if isinstance(node, dict):
            if "uid" in node:
                names[node["uid"]] = node.get("name", "")
            for child in node.get("children", []):
                index(child)

    def leaves(node):
        if isinstance(node, dict):
            if "status" in node and "children" not in node:
                yield node
                return
            for child in node.get("children", []):
                yield from leaves(child)

    index(suites)
    out = []
    for leaf in leaves(suites):
        if leaf["status"] in ("failed", "broken"):
            cls = names.get(leaf.get("parentUid"), "?")
            test = leaf["name"]
            out.append(
                {
                    "key": f"{cls} :: {test}",
                    "cls": cls,
                    "test": test,
                    "status": leaf["status"],
                    "flaky": bool(leaf.get("flaky")),
                    "retries": leaf.get("retriesCount", 0),
                }
            )
    return out


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--build", type=int, help="build number (default: latest)")
    ap.add_argument(
        "--update",
        action="store_true",
        help="persist occurrences/last_seen and append NEW stubs to the registry",
    )
    args = ap.parse_args()

    base, auth = load_env()
    build = args.build or latest_build(base, auth)
    registry = json.loads(REGISTRY.read_text())
    known = registry["failures"]
    failures = collect_failures(base, auth, build)

    # Classes that already have at least one env-data gap on record — a NEW
    # failure in such a class is very likely the same wiped-store root cause.
    envdata_classes = {
        k.split(" :: ", 1)[0]
        for k, v in known.items()
        if v.get("classification") == "env-data"
    }

    new, product, flake, testbug, envdata, untriaged = [], [], [], [], [], []
    for f in failures:
        entry = known.get(f["key"])
        if entry is None:
            new.append(f)
            if args.update:
                known[f["key"]] = {
                    "classification": "untriaged",
                    "reason": "",
                    "tracking": "",
                    "action": "",
                    "first_seen": build,
                    "last_seen": build,
                    "occurrences": 1,
                }
            continue
        if args.update:
            entry["last_seen"] = build
            entry["occurrences"] = entry.get("occurrences", 0) + 1
        bucket = {
            "product-bug": product,
            "flake": flake,
            "test-bug": testbug,
            "env-data": envdata,
        }.get(entry["classification"], untriaged)
        bucket.append((f, entry))

    # Known failures that did NOT recur this build -> candidate resolved.
    failed_keys = {f["key"] for f in failures}
    resolved = [k for k in known if k not in failed_keys]

    bar = "=" * 64
    print(f"\n{bar}\nCI TRIAGE — build #{build}\n{bar}")
    print(f"Total failures: {len(failures)}   "
          f"(product-bug {len(product)}, flake {len(flake)}, "
          f"test-bug {len(testbug)}, env-data {len(envdata)}, NEW {len(new)})\n")

    if new:
        print("🚨 NEW / UNTRIAGED — deep-triage these:")
        for f in new:
            tag = " (marked flaky by retries)" if f["flaky"] else ""
            name = f["test"].lower()
            likely_envdata = (
                f["cls"] in envdata_classes
                or any(h in name for h in EMPTY_DATA_HINTS)
            )
            print(f"   • {f['key']}{tag}")
            if likely_envdata:
                why = (
                    "class already has env-data gaps"
                    if f["cls"] in envdata_classes
                    else "name asserts on data presence"
                )
                print(f"     ⚠ likely ENV-DATA ({why}) — before triaging, open the page "
                      "live and confirm its API/DB actually returns rows; if empty, seed "
                      "(ci/SEEDING_PLAYBOOK.md) rather than filing a bug.")
        print()
    else:
        print("✅ No new failures — every failure is already known.\n")

    if testbug:
        print("🔧 KNOWN TEST-BUGS — these are ours to fix:")
        for f, e in testbug:
            print(f"   • {f['key']}\n     {e['reason']}  [{e.get('tracking','')}]")
        print()

    if envdata:
        print("🌱 KNOWN ENV-DATA GAPS — backing store empty; seed to fix "
              "(ci/SEEDING_PLAYBOOK.md), don't refile as a bug:")
        for f, e in envdata:
            act = e.get("action", "")
            line = f"   • {f['key']}  [{e.get('tracking','')}]"
            print(line + (f"\n     → {act}" if act else ""))
        print()

    if product:
        print("🐛 KNOWN PRODUCT BUGS — leave failing:")
        for f, e in product:
            print(f"   • {f['key']}  [{e.get('tracking','')}]")
        print()

    if flake:
        print("🌊 KNOWN FLAKES — leave failing:")
        for f, e in flake:
            print(f"   • {f['key']}  [{e.get('tracking','')}]")
        print()

    if resolved:
        print("🎉 Known failures that PASSED this build (candidate-resolved):")
        for k in resolved:
            print(f"   • {k}")
        print("   → If consistently green, remove from ci/known-failures.json.\n")

    if args.update:
        REGISTRY.write_text(json.dumps(registry, indent=2) + "\n")
        print(f"(registry updated: {REGISTRY.relative_to(REPO)})\n")

    return 1 if new else 0


if __name__ == "__main__":
    sys.exit(main())
QA_IO_VN_EOF

cat > "toolkit/bug_log.py" <<'QA_IO_VN_EOF'
#!/usr/bin/env python3
"""Log CI product bugs (bugs/bug-NNN.md) into Jira — the engine behind /bug.

``list`` is fully offline (no Jira creds needed): it prints the selectable bugs and
their mapped priority. ``log`` creates a Jira Bug per selected file — into the current
active sprint (auto), at "To Do", carrying the ticket's own priority — attaches the
failure screenshot (.claude/ci-report/<source_test>.png, when present) — then writes the
resulting Jira key + logged state back into the bug file's frontmatter so it is never
double-filed.

Selection:
    (no ids)      -> every bug whose status is not already 'logged'
    bug-001 ...   -> just those ids (accepts 'bug-001', '001', or '1')

Usage:
    python3 ci/bug_log.py list [ids...]
    python3 ci/bug_log.py log --all [flags]         # log every un-logged bug
    python3 ci/bug_log.py log bug-001 bug-003 [flags]
    python3 ci/bug_log.py log --all --dry-run       # show the plan, create nothing

Flags for ``log``:
    --yes           actually create (required unless --dry-run); a deliberate gate
    --dry-run       resolve the active sprint + print the plan, create nothing
    --force         re-file a bug even if it already has a jira_key
    --no-sprint     do not add the issue to any sprint
    --sprint-name N narrow the active-sprint lookup to a board/sprint containing N
    --priority NAME override the mapped priority for every issue (e.g. Medium)
    --status NAME   status to land on (default 'To Do')
    --project KEY   override JIRA_PROJECT for this run
"""
import argparse
import re
import sys
from datetime import datetime
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
import _bugfile  # noqa: E402
import jira as J  # noqa: E402  (ci/jira.py, not the pip package — ci/ is first on sys.path)

REPO = Path(__file__).resolve().parent.parent
BUGS_DIR = REPO / "bugs"
CI_REPORT_DIR = REPO / ".claude" / "ci-report"
JENKINS_ENV = REPO / ".claude" / "jenkins.env"
APP_PROPS = REPO / "config" / "application.properties"

# Ticket priority code -> Jira priority name.
PRIORITY_MAP = {"P1": "Highest", "P2": "High", "P3": "Medium", "P4": "Low"}
DEFAULT_STATUS = "To Do"
MAP_COMMENT = re.compile(r"<!--\s*map:\s*[\w.$]+\s*-->")

# Ticket 'system' -> config/application.properties key(s) for the app-under-test URL
# (first key that resolves wins).
SYSTEM_URL_PROPS = {
    "app-a": ("url.ui.app-a",),
    "app-b": ("url.ui.app-b",),
}


def _kv_file(path):
    """Parse a simple KEY=VALUE file (env/properties); comments and blanks skipped."""
    cfg = {}
    if path.is_file():
        for line in path.read_text().splitlines():
            line = line.strip()
            if not line or line.startswith("#") or "=" not in line:
                continue
            k, v = line.split("=", 1)
            cfg[k.strip()] = v.strip().strip('"').strip("'")
    return cfg


def app_url(system):
    """Resolve the running app URL for the ticket's system from application.properties."""
    props = _kv_file(APP_PROPS)
    for key in SYSTEM_URL_PROPS.get((system or "").strip().lower(), ()):
        if props.get(key):
            return props[key]
    return ""


def ci_build_url(build):
    """URL of the Jenkins run that caught the bug (JENKINS_BASE + JENKINS_JOB + build)."""
    cfg = _kv_file(JENKINS_ENV)
    base, job = cfg.get("JENKINS_BASE", ""), cfg.get("JENKINS_JOB", "")
    return f"{base}{job}/{build}/" if base and job and build else ""


def dev_links(fm):
    """Developer-facing links: running environment + the CI/CD run + Allure report."""
    lines = []
    url = app_url(fm.get("system"))
    if url:
        lines.append(f"Running environment ({fm.get('system')}): {url}")
    burl = ci_build_url(fm.get("build"))
    if burl:
        lines.append(f"CI/CD run that caught it: {burl}")
        lines.append(f"Test report (Allure): {burl}allure/")
    return lines


def _norm_id(token):
    """Accept 'bug-001', 'bug-1', '001', or '1' -> canonical 'bug-001'."""
    m = re.search(r"(\d+)", token)
    return f"bug-{int(m.group(1)):03d}" if m else token.strip()


def load_bugs():
    """Return [(path, frontmatter, body)] for every bugs/bug-*.md, id-sorted."""
    out = []
    if BUGS_DIR.exists():
        for p in sorted(BUGS_DIR.glob("bug-*.md")):
            fm, body = _bugfile.parse(p)
            out.append((p, fm, body))
    return out


def select(bugs, ids):
    """Filter loaded bugs by explicit ids, or return all when ids is empty."""
    if not ids:
        return bugs
    wanted = {_norm_id(x) for x in ids}
    chosen = [b for b in bugs if b[1].get("id") in wanted]
    found = {b[1].get("id") for b in chosen}
    missing = wanted - found
    if missing:
        print(f"Warning: no bug file for: {', '.join(sorted(missing))}", file=sys.stderr)
    return chosen


def mapped_priority(fm, override):
    return override or PRIORITY_MAP.get(fm.get("priority", "P3"), "Medium")


def build_description(fm, body):
    """Plain-text Jira description from the ticket body (drop heading + markdown)."""
    lines = []
    for ln in body.splitlines():
        if ln.strip().startswith("### ") or MAP_COMMENT.search(ln):
            continue
        lines.append(ln)
    text = "\n".join(lines).strip()
    text = re.sub(r"\*\*(.+?)\*\*", r"\1", text)  # drop bold markers
    text = text.replace("`", "")  # drop inline code ticks
    parts = [text]
    links = dev_links(fm)
    if links:
        parts.append("Links for Dev:\n" + "\n".join(f"• {ln}" for ln in links))
    footer = f"———\nFiled automatically by CI triage. Source test: {fm.get('source_test', '?')}"
    if fm.get("build"):
        footer += f" · CI build #{fm['build']}"
    parts.append(footer)
    return "\n\n".join(parts)


def print_table(rows, override_priority):
    if not rows:
        print("No matching bugs.")
        return
    print(f"{'ID':<9}{'STATUS':<8}{'PRIORITY':<10}{'JIRA':<12}TITLE")
    for _, fm, _b in rows:
        pri = mapped_priority(fm, override_priority)
        print(
            f"{fm.get('id',''):<9}{fm.get('status','open'):<8}{pri:<10}"
            f"{fm.get('jira_key','') or '-':<12}{fm.get('title','')}"
        )


def do_list(args):
    print_table(select(load_bugs(), args.ids), None)


def do_log(args):
    all_bugs = load_bugs()
    if not args.ids and not args.all:
        raise SystemExit("Refusing to log: pass explicit bug ids or --all.")

    selected = all_bugs if args.all and not args.ids else select(all_bugs, args.ids)
    # Skip already-logged unless --force.
    pending, skipped = [], []
    for b in selected:
        if b[1].get("status") == "logged" and b[1].get("jira_key") and not args.force:
            skipped.append(b)
        else:
            pending.append(b)

    for _, fm, _b in skipped:
        print(f"skip  {fm.get('id')}  already logged as {fm.get('jira_key')}")
    if not pending:
        print("Nothing to log — every selected bug is already filed (use --force to re-file).")
        return

    project = args.project
    sprint = None
    if not args.no_sprint:
        try:
            base, auth, cfg = J.client()
            project = project or cfg.get("JIRA_PROJECT")
            if not project:
                raise SystemExit("No --project or JIRA_PROJECT set.")
            sprint = J.active_sprint(base, auth, project, args.sprint_name)
        except SystemExit:
            if not args.dry_run:
                raise
            print("(dry-run) Jira not configured — active sprint unknown.", file=sys.stderr)
        except Exception as e:  # connectivity — tolerate on dry-run, surface on a real log
            if not args.dry_run:
                raise
            print(f"(dry-run) could not resolve active sprint: {e}", file=sys.stderr)

    sprint_label = "none" if args.no_sprint else (sprint.get("name") if sprint else "auto (resolved at create)")
    print(
        f"Plan: file {len(pending)} bug(s) into project {project or '?'} "
        f"at '{args.status}' · sprint: {sprint_label}"
    )
    print_table(pending, args.priority)

    if args.dry_run:
        print("\n(dry-run) no Jira issues created, no files changed.")
        return
    if not args.yes:
        raise SystemExit("\nRefusing to create Jira issues without --yes.")

    base, auth, cfg = J.client()
    project = project or cfg.get("JIRA_PROJECT")
    logged = 0
    for path, fm, body in pending:
        pri = mapped_priority(fm, args.priority)
        labels = ["ci-triage", "automation"]
        if fm.get("system"):
            labels.append(fm["system"].lower().replace(" ", "-"))
        try:
            res, pr_set = J.create_issue(
                base, auth, project, fm.get("title", "Untitled bug"),
                build_description(fm, body), "Bug", pri, labels,
            )
        except Exception as e:
            print(f"FAIL  {fm.get('id')}  create failed: {e}", file=sys.stderr)
            continue
        key = res.get("key")
        notes = [] if pr_set else ["priority not set"]

        if sprint:
            try:
                J.add_to_sprint(base, auth, sprint["id"], key)
            except Exception as e:  # noqa: BLE001
                notes.append(f"sprint not set ({e})")
        if args.status:
            try:
                cur = (J.get_issue(base, auth, key, "status").get("fields", {}).get("status") or {}).get("name", "")
                if cur.lower() != args.status.lower():
                    J.do_transition(base, auth, key, args.status)
            except Exception:  # noqa: BLE001
                notes.append(f"status not moved to {args.status}")

        shot = CI_REPORT_DIR / f"{fm.get('source_test', '')}.png"
        if fm.get("source_test") and shot.is_file():
            try:
                J.add_attachment(base, auth, key, str(shot))
            except Exception as e:  # noqa: BLE001
                notes.append(f"screenshot not attached ({e})")
        else:
            notes.append("no screenshot found to attach")

        fm.update(
            {
                "status": "logged",
                "jira_key": key,
                "jira_url": f"{base}/browse/{key}",
                "jira_logged_at": datetime.now().isoformat(timespec="seconds"),
                "jira_sprint": sprint.get("name", "") if sprint else "",
            }
        )
        _bugfile.write(path, fm, body)
        logged += 1
        tail = ("  [" + "; ".join(notes) + "]") if notes else ""
        print(f"OK    {fm.get('id')}  -> {key}  {base}/browse/{key}{tail}")

    print(f"\nLogged {logged}/{len(pending)} bug(s) to Jira. Frontmatter updated (status: logged).")


def main():
    ap = argparse.ArgumentParser(description="Log CI product bugs into Jira.")
    sub = ap.add_subparsers(dest="cmd", required=True)

    lp = sub.add_parser("list", help="Preview selectable bugs (offline).")
    lp.add_argument("ids", nargs="*")

    gp = sub.add_parser("log", help="Create Jira issues for selected bugs.")
    gp.add_argument("ids", nargs="*")
    gp.add_argument("--all", action="store_true")
    gp.add_argument("--yes", action="store_true")
    gp.add_argument("--dry-run", action="store_true")
    gp.add_argument("--force", action="store_true")
    gp.add_argument("--no-sprint", action="store_true")
    gp.add_argument("--sprint-name")
    gp.add_argument("--priority")
    gp.add_argument("--status", default=DEFAULT_STATUS)
    gp.add_argument("--project")

    args = ap.parse_args()
    if args.cmd == "list":
        do_list(args)
    elif args.cmd == "log":
        do_log(args)


if __name__ == "__main__":
    main()
QA_IO_VN_EOF

cat > "toolkit/bugs_split.py" <<'QA_IO_VN_EOF'
#!/usr/bin/env python3
"""Split the latest /ci product-bug report into one file per bug under bugs/.

Reads ``.claude/ci-report/bug-tickets.md`` (written by /ci Phase 4) and writes one
``bugs/bug-NNN.md`` per confirmed product-bug ticket, with a small frontmatter block
carrying the triage metadata and the Jira-logging state.

Idempotent by SOURCE TEST: a bug is keyed by its hidden ``<!-- map: FQN -->`` marker
(or the visible "Test reference" field). Re-running /ci reuses the same ``bug-NNN`` id
for the same source test and PRESERVES any logging metadata that /bug wrote back
(``status``/``jira_key``/…), so /ci never un-logs or renumbers a bug you already filed.

Existing bug files whose source test no longer appears in the current report are left
untouched — they stay as a record of a filed bug (and its Jira link).

Usage:
    python3 ci/bugs_split.py                      # split the real ci-report tickets
    python3 ci/bugs_split.py --tickets f.md --out /tmp/bugs   # test against a fixture
"""
import argparse
import json
import re
import sys
from datetime import date
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
import _bugfile  # noqa: E402

REPO = Path(__file__).resolve().parent.parent
CI_REPORT = REPO / ".claude" / "ci-report"
DEFAULT_TICKETS = CI_REPORT / "bug-tickets.md"
FAILURES = CI_REPORT / "failures.json"
DEFAULT_BUGS_DIR = REPO / "bugs"

MAP_COMMENT = re.compile(r"<!--\s*map:\s*([\w.$]+)\s*-->")
TITLE_RE = re.compile(r"^###\s+(.+)$", re.M)


def _field(block, name):
    """Return the inline value of a ``**Name:** value`` marker (or "")."""
    m = re.search(r"\*\*" + re.escape(name) + r":\*\*[ \t]*([^\n]*)", block)
    return m.group(1).strip() if m else ""


def _source_test(block):
    """The FQN this ticket maps to: hidden map marker first, then Test reference."""
    m = MAP_COMMENT.search(block)
    if m:
        return m.group(1).strip()
    ref = _field(block, "Test reference") or _field(block, "Source test")
    sm = re.search(r"`([^`]+)`", ref)
    if sm:
        return sm.group(1).split(" ")[0].strip()
    fm = re.search(r"\b([a-z][\w.]*\.[A-Z]\w*\.\w+)\b", ref)
    return fm.group(1) if fm else ""


def _system(title, block):
    """Prefer the ``[System]`` bracket in the title; fall back to the System field."""
    bm = re.match(r"\[([^\]]+)\]", title)
    if bm:
        return bm.group(1).strip()
    val = _field(block, "System")
    return re.split(r"[|/]", val)[0].strip() if val else ""


def _priority_code(block):
    """Extract the P1–P4 code from the Priority field (defaults to P3)."""
    m = re.search(r"P[1-4]", _field(block, "Priority"))
    return m.group(0) if m else "P3"


def _severity(block):
    m = re.match(r"([A-Za-z]+)", _field(block, "Severity"))
    return m.group(1) if m else ""


def parse_blocks(md):
    """Return a list of ticket dicts parsed from a bug-tickets.md body."""
    tickets = []
    for block in md.split("\n---\n"):
        if "### " not in block:
            continue
        if not (MAP_COMMENT.search(block) or "Test reference" in block or "Source test" in block):
            continue
        tm = TITLE_RE.search(block)
        if not tm:
            continue
        title = re.sub(r"^[🐛\s]*", "", tm.group(1)).strip()
        src = _source_test(block)
        if not src:
            continue
        tickets.append(
            {
                "source_test": src,
                "title": title,
                "system": _system(title, block),
                "severity": _severity(block),
                "priority": _priority_code(block),
                "body": block.strip(),
            }
        )
    return tickets


def _build_number(md):
    m = re.search(r"Build\s+#(\d+)", md)
    if m:
        return m.group(1)
    if FAILURES.exists():
        try:
            return str(json.loads(FAILURES.read_text()).get("build", "")) or ""
        except (ValueError, OSError):
            return ""
    return ""


def load_existing(bugs_dir):
    """Map ``source_test -> (id, frontmatter, path)`` and the max numeric id seen."""
    by_src, max_n = {}, 0
    if bugs_dir.exists():
        for p in sorted(bugs_dir.glob("bug-*.md")):
            fm, _ = _bugfile.parse(p)
            m = re.search(r"(\d+)", fm.get("id", p.stem))
            if m:
                max_n = max(max_n, int(m.group(1)))
            src = fm.get("source_test")
            if src:
                by_src[src] = (fm.get("id", p.stem), fm, p)
    return by_src, max_n


def main():
    ap = argparse.ArgumentParser(description="Split bug-tickets.md into bugs/bug-NNN.md files.")
    ap.add_argument("--tickets", default=str(DEFAULT_TICKETS), help="bug-tickets.md to read")
    ap.add_argument("--out", default=str(DEFAULT_BUGS_DIR), help="output bugs/ directory")
    args = ap.parse_args()

    tickets_path = Path(args.tickets)
    bugs_dir = Path(args.out)
    if not tickets_path.exists():
        print(f"No {tickets_path} — nothing to split.")
        return

    md = tickets_path.read_text(encoding="utf-8")
    build = _build_number(md)
    tickets = parse_blocks(md)
    bugs_dir.mkdir(parents=True, exist_ok=True)
    by_src, max_n = load_existing(bugs_dir)
    today = date.today().isoformat()

    written, new_count, updated_count = [], 0, 0
    for t in tickets:
        src = t["source_test"]
        if src in by_src:
            bug_id, old_fm, path = by_src[src]
            updated_count += 1
        else:
            max_n += 1
            bug_id = f"bug-{max_n:03d}"
            old_fm, path = {}, bugs_dir / f"{bug_id}.md"
            new_count += 1
        fm = {
            "id": bug_id,
            "source_test": src,
            "title": t["title"],
            "system": t["system"],
            "severity": t["severity"],
            "priority": t["priority"],
            "build": build,
            "generated": today,
            # Preserve logging state written by /bug across regeneration.
            "status": old_fm.get("status", "open") or "open",
            "jira_key": old_fm.get("jira_key", ""),
            "jira_url": old_fm.get("jira_url", ""),
            "jira_logged_at": old_fm.get("jira_logged_at", ""),
            "jira_sprint": old_fm.get("jira_sprint", ""),
        }
        _bugfile.write(path, fm, t["body"])
        written.append((bug_id, fm["status"], t["title"]))

    if not written:
        print(f"No product-bug tickets in {tickets_path} (build #{build or '?'}) — nothing to split.")
        return

    print(
        f"Split {len(written)} product-bug ticket(s) from build #{build or '?'} into {bugs_dir}/ "
        f"({new_count} new, {updated_count} refreshed):"
    )
    for bug_id, status, title in written:
        print(f"  {bug_id}  [{status:<6}] {title}")


if __name__ == "__main__":
    main()
QA_IO_VN_EOF

cat > "toolkit/bug_index.py" <<'QA_IO_VN_EOF'
#!/usr/bin/env python3
"""Active-bug index — a readable HTML dashboard of confirmed bugs in the latest CI.

Audience: Dev, BA, PO, Team Lead. The cards read like proper defect reports
(ISTQB-aligned) — no test-automation jargon. It reads the latest run
(`.claude/ci-report/failures.json` + the bug report `bug-tickets.md`), shows only
confirmed product bugs (failures without a bug report, and anything already
fixed, are hidden), and embeds the real failure screenshot when one is saved next
to the report (`.claude/ci-report/<test>.png`).

  python3 ci/bug_index.py                 # latest run -> ci/active-bugs.html
  python3 ci/bug_index.py --out foo.html  # custom output path
  python3 ci/bug_index.py --open          # also open it in the default browser

Source priority:
  1. .claude/ci-report/failures.json (+ bug-tickets.md)  — the latest run
  2. ci/known-failures.json                              — registry snapshot fallback
"""
import argparse
import base64
import datetime as _dt
import html
import json
import re
import sys
import webbrowser
from pathlib import Path

REPO = Path(__file__).resolve().parent.parent
CI_REPORT = REPO / ".claude" / "ci-report"
FAILURES = CI_REPORT / "failures.json"
TICKETS = CI_REPORT / "bug-tickets.md"
REGISTRY = REPO / "ci" / "known-failures.json"
DEFAULT_OUT = REPO / "ci" / "active-bugs.html"

# classification -> (label, css-class, emoji, blurb). Only "real bug" buckets are
# rendered; "no bug report" failures and fixed items are filtered out (see render()).
META = {
    "product-bug": ("Bug", "product", "🐛", "Confirmed defect — file in the tracker"),
    "flake": ("Unstable", "flake", "🌊", "Environment/timing instability"),
    "test-bug": ("Test issue", "testbug", "🔧", "Issue in the automated check"),
    "env-data": ("Data gap", "envdata", "🌱", "Missing data in the environment"),
    "untriaged": ("No bug report", "new", "🔍", ""),
    "new": ("No bug report", "new", "🔍", ""),
}
ORDER = ["product-bug", "flake", "test-bug", "env-data"]

# Sections handled specially or hidden from the readable report.
SHOT_LABELS = re.compile(r"(?i)^(screenshot|attachment)")
# Internal automation references — parsed for screenshot mapping (Test reference)
# but NOT shown to Dev/BA/PO: the FQCN, memory slug and registry key are noise in a
# reader-facing defect report, and the trivial "Issue type: Bug" duplicates the badge.
HIDE_LABELS = re.compile(
    r"(?i)^(test reference|source test|known[- ]failure tracking|issue type)\b")
# Hidden test↔ticket link: `<!-- map: <fullName> -->` placed under a ticket's title.
# Lets a ticket name the failing test (so its screenshot + sections attach) without a
# reader-facing "Test reference" row. Parsed only; never rendered.
MAP_COMMENT = re.compile(r"<!--\s*map:\s*([\w.$]+)\s*-->")
# Lines that leak internal tooling — scrubbed defensively (the source should
# already be clean; this guarantees nothing tool-specific reaches the reader).
JARGON = re.compile(r"(?i)playwright|(?<![a-z])mcp(?![a-z])|browser_|allure")


def esc(s):
    return html.escape(str(s or ""))


def scrub(text):
    return "\n".join(ln for ln in (text or "").splitlines() if not JARGON.search(ln))


def md_inline(s):
    s = esc(s)
    s = re.sub(r"(https?://[^\s<)]+)",
               r'<a href="\1" target="_blank" rel="noopener">\1</a>', s)
    s = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", s)
    s = re.sub(r"`([^`]+)`", r"<code>\1</code>", s)
    return s


def is_fixed(action):
    a = (action or "").lower()
    return a.startswith("fixed") or "(local green" in a or "fixed-pending" in a


def short_class(fqcn):
    return fqcn.rsplit(".", 1)[-1] if fqcn else fqcn


def humanize_method(method):
    m = re.sub(r"^(test|should)", "", method or "")
    m = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", " ", m)
    m = re.sub(r"(?<=[A-Z])(?=[A-Z][a-z])", " ", m)
    return m.strip() or method


def first_line(content):
    for ln in (content or "").splitlines():
        if ln.strip():
            return re.sub(r"^[-*\d.)\s]+", "", ln.strip())
    return ""


def first_clause(text):
    return re.split(r"\s+[—-]\s+", text or "", maxsplit=1)[0].strip()


def screenshot_uri(full):
    """Inline the saved failure screenshot (<test>.png) as a data URI, if present."""
    p = CI_REPORT / f"{full}.png"
    if p.exists() and p.stat().st_size:
        b64 = base64.b64encode(p.read_bytes()).decode()
        return f"data:image/png;base64,{b64}"
    return ""


# --------------------------------------------------------------------------- #
# Parse bug-tickets.md -> {sourceTestFullName: {title, sections[], lookup{}}}    #
# --------------------------------------------------------------------------- #
def parse_tickets(md):
    tickets = {}
    if not md:
        return tickets
    blocks = [b for b in md.split("\n---\n")
              if "### " in b and (MAP_COMMENT.search(b)
                                  or "Test reference" in b or "Source test" in b)]
    for b in blocks:
        tm = re.search(r"^###\s+(.+)$", b, re.M)
        title = re.sub(r"^[🐛\s]*", "", tm.group(1)).strip() if tm else ""
        markers = list(re.finditer(r"\*\*([^*\n]+?):\*\*", b))
        sections, lookup = [], {}
        for i, m in enumerate(markers):
            label = m.group(1).strip()
            start = m.end()
            end = markers[i + 1].start() if i + 1 < len(markers) else len(b)
            # Drop a trailing on-top/below separator (em-dash or hyphen rule) so it
            # doesn't tail the last reader-facing section in the report.
            content = re.sub(r"\n*\s*[—-]{3,}\s*$", "", b[start:end].strip()).strip()
            sections.append((label, content))
            lookup[label] = content
        # Lead paragraph: the reader-facing summary that sits above the first labelled
        # field (the current template has no "**Summary:**" label). Used as the card
        # description when no explicit Summary field is present.
        head = b[: markers[0].start()] if markers else b
        if tm:
            head = head.replace(tm.group(0), "", 1)
        lead = first_line(MAP_COMMENT.sub("", head))
        # Prefer the hidden `<!-- map: <fullName> -->` marker; fall back to a
        # (legacy) visible "Test reference"/"Source test" field for older tickets.
        cm = MAP_COMMENT.search(b)
        key = cm.group(1).strip() if cm else None
        if not key:
            ref = lookup.get("Test reference", "") or lookup.get("Source test", "")
            sm = re.search(r"`([^`]+)`", ref)
            key = sm.group(1).strip() if sm else None
            # fall back: derive key from any FQCN in the reference
            if not key:
                fm = re.search(r"\b([a-z][\w.]*\.[A-Z]\w*\.\w+)\b", ref)
                key = fm.group(1) if fm else None
        if not key:
            continue
        # the key may carry a trailing "(path:line)"; keep only the FQCN-ish head
        key = key.split(" ")[0].strip()
        tickets[key] = {"title": title, "sections": sections, "lookup": lookup,
                        "lead": lead}
    return tickets


def trace_for(full, fallback):
    p = CI_REPORT / f"{full}.txt"
    if p.exists():
        return p.read_text(encoding="utf-8", errors="replace")
    return fallback or ""


# --------------------------------------------------------------------------- #
# Build rows                                                                    #
# --------------------------------------------------------------------------- #
def gather():
    if FAILURES.exists():
        data = json.loads(FAILURES.read_text())
        tickets = parse_tickets(TICKETS.read_text() if TICKETS.exists() else "")
        rows = []
        for f in data.get("failures", []):
            full = f.get("fullName", "")
            row = {
                "title": humanize_method(f.get("method", "")),
                "klass": short_class(f.get("class", "")),
                "fqcn": full,
                "message": f.get("message", ""),
                "trace": trace_for(full, f.get("trace", "")),
                "sections": [],
                "screenshot": screenshot_uri(full),
                "fixed": False,
            }
            t = tickets.get(full)
            if t:
                lk = t["lookup"]
                row.update({
                    "cls": "product-bug",
                    "title": t["title"] or row["title"],
                    "summary": first_line(lk.get("Summary")) or t.get("lead", ""),
                    "sections": t["sections"],
                    "system": first_line(lk.get("System")),
                    "feature": first_line(lk.get("Feature / Component")),
                    "severity": lk.get("Severity", ""),
                    "priority": lk.get("Priority", ""),
                    "repro": lk.get("Reproducibility", ""),
                    "tracking": lk.get("Known-failure tracking", ""),
                })
            else:
                row["cls"] = "untriaged"
            rows.append(row)
        return {"build": data.get("build"), "result": data.get("result", ""),
                "source": "Latest CI run", "rows": rows}

    sys.stderr.write("[bug_index] no .claude/ci-report/failures.json — run /ci first; "
                     "rendering ci/known-failures.json snapshot.\n")
    reg = json.loads(REGISTRY.read_text())["failures"]
    rows = []
    for key, e in reg.items():
        klass, _, test = key.partition(" :: ")
        cls = e.get("classification", "new")
        sections = []
        if e.get("reason"):
            sections.append(("Summary", e["reason"]))
        if e.get("tracking"):
            sections.append(("Tracking", e["tracking"]))
        rows.append({
            "cls": cls if cls in META else "new",
            "title": test, "klass": klass, "fqcn": "",
            "summary": e.get("reason", ""), "message": "", "trace": "",
            "sections": sections, "screenshot": "",
            "tracking": e.get("tracking", ""),
            "fixed": is_fixed(e.get("action", "")),
        })
    return {"build": None, "result": "registry snapshot",
            "source": "Registry snapshot", "rows": rows}


# --------------------------------------------------------------------------- #
# Render                                                                        #
# --------------------------------------------------------------------------- #
def sev_class(severity):
    s = (severity or "").lower()
    if s.startswith("blocker") or s.startswith("critical"):
        return "sev-crit"
    if s.startswith("major"):
        return "sev-major"
    if s.startswith("minor"):
        return "sev-minor"
    if s.startswith("trivial"):
        return "sev-trivial"
    return ""


def sev_rank(severity):
    return {"sev-crit": 4, "sev-major": 3, "sev-minor": 2, "sev-trivial": 1}.get(
        sev_class(severity), 0)


def render_content(content):
    out, buf, cur = [], [], None

    def flush():
        nonlocal buf, cur
        if buf:
            tag = "ol" if cur == "ol" else "ul"
            out.append(f"<{tag}>" + "".join(f"<li>{md_inline(x)}</li>" for x in buf)
                       + f"</{tag}>")
        buf, cur = [], None

    for line in (content or "").splitlines():
        t = line.strip()
        if not t:
            continue
        mo = re.match(r"^[-*]\s+(.*)", t)
        mn = re.match(r"^\d+[.)]\s+(.*)", t)
        if mo:
            if cur != "ul":
                flush(); cur = "ul"
            buf.append(mo.group(1))
        elif mn:
            if cur != "ol":
                flush(); cur = "ol"
            buf.append(mn.group(1))
        else:
            flush()
            out.append(f"<p>{md_inline(t)}</p>")
    flush()
    return "".join(out)


def render_sections(sections, screenshot):
    parts = []
    for label, content in sections:
        if HIDE_LABELS.match(label):
            continue
        if SHOT_LABELS.match(label):
            if not screenshot:
                continue
            val = (f'<a href="{screenshot}" target="_blank" rel="noopener">'
                   f'<img class="shot" src="{screenshot}" alt="Failure screenshot" '
                   f'loading="lazy"></a>')
            label = "Screenshot"
        else:
            body = scrub(content)
            if not body.strip():
                continue
            val = render_content(body)
        parts.append(f'<div class="sec"><div class="sk">{esc(label)}</div>'
                     f'<div class="sv">{val}</div></div>')
    return "".join(parts)


def render(ctx):
    # Only confirmed bugs: drop "no bug report" failures and anything already fixed.
    rows = [r for r in ctx["rows"]
            if r["cls"] not in ("untriaged", "new") and not r["fixed"]]

    counts = {}
    for r in rows:
        counts[r["cls"]] = counts.get(r["cls"], 0) + 1
    total = len(rows)
    product = counts.get("product-bug", 0)
    crit = sum(1 for r in rows if sev_class(r.get("severity")) == "sev-crit")
    now = _dt.datetime.now().strftime("%Y-%m-%d %H:%M")

    build = ctx.get("build")
    result = ctx.get("result", "")
    res_class = {"UNSTABLE": "r-unstable", "FAILURE": "r-fail",
                 "SUCCESS": "r-ok"}.get(str(result).upper(), "r-info")

    def stat(num, label, css=""):
        return (f'<div class="stat {css}"><div class="num">{num}</div>'
                f'<div class="lbl">{label}</div></div>')

    build_disp = f"#{build}" if build else "—"
    stats = "".join([
        stat(build_disp, "Build"),
        f'<div class="stat"><div class="num {res_class}">{esc(result) or "—"}</div>'
        '<div class="lbl">Result</div></div>',
        stat(total, "Open bugs", "s-active"),
        stat(crit, "Critical / Blocker", "s-crit"),
    ])

    chips = ['<button class="chip active" data-filter="all">All</button>']
    for cls in ORDER:
        n = counts.get(cls, 0)
        if not n:
            continue
        label, css, emoji, _ = META[cls]
        chips.append(f'<button class="chip" data-filter="{css}">'
                     f'{emoji} {label} <span class="cn">{n}</span></button>')
    chips_html = "".join(chips)

    cards = []
    for cls in ORDER:
        group = [r for r in rows if r["cls"] == cls]
        if not group:
            continue
        group.sort(key=lambda r: (-sev_rank(r.get("severity")), r["title"]))
        label, css, emoji, blurb = META[cls]
        head = f'<h2 class="grp {css}">{emoji} {label} <span class="gc">{len(group)}</span>'
        if blurb:
            head += f' <span class="gb">{esc(blurb)}</span>'
        cards.append(head + "</h2>")
        cards.extend(card(r) for r in group)
    cards_html = "\n".join(cards) or (
        '<div class="empty">✅ No confirmed bugs in this build.</div>')

    page = (
        "<!doctype html><html lang='en'><head><meta charset='utf-8'>"
        "<meta name='viewport' content='width=device-width,initial-scale=1'>"
        "<title>CI Bug Report</title><style>" + CSS + "</style></head><body>"
        "<header class='top'><div class='wrap'>"
        "<div class='brand'><span class='dot'></span>CI&nbsp;Bug&nbsp;Report</div>"
        f"<div class='meta'>{esc(ctx.get('source',''))} · updated {now}</div>"
        "</div></header><main class='wrap'>"
        f"<section class='stats'>{stats}</section>"
        "<div class='controls'><input id='q' type='search' "
        "placeholder='Search by feature, summary, area…' autocomplete='off'>"
        f"<div class='chips'>{chips_html}"
        '<button id="exp" class="chip">⤢ Expand all</button></div></div>'
        f"<section id='list'>{cards_html}</section>"
        "<footer class='foot'>Confirmed defects only — items still being fixed and "
        "items without a bug report are not shown.</footer>"
        "</main><script>" + JS + "</script></body></html>"
    )
    return page, total, product


def card(r):
    label, css, emoji, _ = META[r["cls"]]
    badges = [f'<span class="badge b-{css}">{emoji} {esc(label)}</span>']
    sev = r.get("severity")
    if sev:
        badges.append(f'<span class="badge {sev_class(sev)}" title="{esc(sev)}">'
                      f'{esc(first_clause(sev))}</span>')
    pri = r.get("priority")
    if pri:
        badges.append(f'<span class="badge b-pri" title="{esc(pri)}">'
                      f'{esc(first_clause(pri))}</span>')
    repro = r.get("repro")
    if repro:
        badges.append(f'<span class="badge b-repro" title="{esc(repro)}">'
                      f'↻ {esc(first_clause(repro))}</span>')
    if r.get("system"):
        badges.append(f'<span class="badge b-sys">{esc(r["system"])}</span>')
    badges_html = "".join(badges)

    body = ""
    if r.get("feature"):
        body += f'<div class="feat">{esc(r["feature"])}</div>'
    desc = r.get("summary") or r.get("message")
    if desc:
        body += f'<p class="reason">{md_inline(desc)}</p>'

    if r.get("sections"):
        sec_html = render_sections(r["sections"], r.get("screenshot"))
        if sec_html:
            body += ('<details class="report"><summary>📋 Full bug report</summary>'
                     f'<div class="report-body">{sec_html}</div></details>')
    if r.get("trace"):
        tr = r["trace"]
        if len(tr) > 8000:
            tr = tr[:8000] + "\n… (truncated)"
        body += (f'<details class="trace"><summary>🧵 Technical log</summary>'
                 f'<pre>{esc(tr)}</pre></details>')

    hay_parts = [r.get(k, "") for k in
                 ("title", "summary", "klass", "message", "system", "feature", "cls")]
    hay_parts += [c for _, c in r.get("sections", [])]
    hay = esc(" ".join(str(x) for x in hay_parts)).lower()

    return (
        f'<article class="bug {css}" data-cls="{css}" data-hay="{hay}">'
        f'<div class="bhead"><div class="badges">{badges_html}</div></div>'
        f'<div class="test">{esc(r["title"])}</div>{body}</article>'
    )


CSS = """
:root{
  --bg:#0d1117;--panel:#161b22;--panel2:#1c2330;--line:#26303d;--ink:#e6edf3;
  --mut:#8b98a9;--mut2:#5c6b7d;
  --product:#f85149;--flake:#e3b341;--testbug:#58a6ff;--envdata:#3fb950;--new:#bc8cff;
}
*{box-sizing:border-box}
html{scroll-behavior:smooth}
body{margin:0;background:radial-gradient(1200px 600px at 80% -10%,#1b2433 0,var(--bg) 55%);
  color:var(--ink);font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif}
.wrap{max-width:1080px;margin:0 auto;padding:0 22px}
.top{border-bottom:1px solid var(--line);background:rgba(13,17,23,.72);
  backdrop-filter:blur(8px);position:sticky;top:0;z-index:5}
.top .wrap{display:flex;align-items:center;justify-content:space-between;
  flex-wrap:wrap;gap:8px;padding:16px 22px}
.brand{font-size:20px;font-weight:700;display:flex;align-items:center;gap:10px}
.dot{width:11px;height:11px;border-radius:50%;background:var(--product);
  box-shadow:0 0 0 4px rgba(248,81,73,.18);animation:pulse 2.4s infinite}
@keyframes pulse{0%,100%{opacity:1}50%{opacity:.4}}
.meta{color:var(--mut);font-size:12.5px}
main{padding-bottom:64px}
.stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;margin:24px 0}
.stat{background:linear-gradient(180deg,var(--panel2),var(--panel));border:1px solid var(--line);
  border-radius:14px;padding:18px 14px;text-align:center}
.stat .num{font-size:30px;font-weight:800;letter-spacing:-.5px}
.stat .lbl{color:var(--mut);font-size:11px;text-transform:uppercase;letter-spacing:.6px;margin-top:4px}
.s-active .num{color:var(--ink)}.s-crit .num{color:var(--product)}
.r-unstable{color:var(--flake)}.r-fail{color:var(--product)}.r-ok{color:var(--envdata)}.r-info{color:var(--mut)}
.controls{display:flex;flex-wrap:wrap;gap:12px;align-items:center;margin:8px 0 18px;
  position:sticky;top:64px;z-index:4;padding:10px 0;background:linear-gradient(180deg,var(--bg) 62%,transparent)}
#q{flex:1;min-width:220px;background:var(--panel);border:1px solid var(--line);color:var(--ink);
  padding:10px 14px;border-radius:10px;font-size:14px;outline:none}
#q:focus{border-color:var(--testbug);box-shadow:0 0 0 3px rgba(88,166,255,.15)}
.chips{display:flex;flex-wrap:wrap;gap:8px}
.chip{cursor:pointer;background:var(--panel);border:1px solid var(--line);color:var(--mut);
  padding:7px 12px;border-radius:999px;font-size:12.5px;font-weight:600;transition:.12s}
.chip:hover{color:var(--ink);border-color:var(--mut2)}
.chip.active{background:var(--ink);color:#0d1117;border-color:var(--ink)}
.chip .cn{opacity:.6;margin-left:3px}
#exp{margin-left:auto}
.grp{font-size:14px;font-weight:700;margin:26px 0 12px;display:flex;align-items:center;
  gap:10px;flex-wrap:wrap;padding-bottom:8px;border-bottom:1px solid var(--line)}
.grp .gc{background:var(--panel2);border:1px solid var(--line);border-radius:999px;
  padding:1px 9px;font-size:12px;color:var(--mut)}
.grp .gb{font-weight:400;color:var(--mut2);font-size:12.5px}
.bug{background:var(--panel);border:1px solid var(--line);border-left:3px solid var(--mut2);
  border-radius:12px;padding:14px 16px;margin:10px 0;transition:.12s}
.bug:hover{border-color:var(--mut2)}
.bug.product{border-left-color:var(--product)}.bug.flake{border-left-color:var(--flake)}
.bug.testbug{border-left-color:var(--testbug)}.bug.envdata{border-left-color:var(--envdata)}
.bhead{display:flex;justify-content:space-between;align-items:flex-start;gap:12px;flex-wrap:wrap}
.badges{display:flex;gap:6px;flex-wrap:wrap}
.badge{font-size:11px;font-weight:700;padding:3px 9px;border-radius:999px;white-space:nowrap}
.b-product{background:rgba(248,81,73,.14);color:#ff9a93}
.b-flake{background:rgba(227,179,65,.14);color:#f0d080}
.b-testbug{background:rgba(88,166,255,.14);color:#9cccff}
.b-envdata{background:rgba(63,185,80,.14);color:#86e08f}
.b-sys{background:rgba(139,152,169,.16);color:#c7d0db}
.b-pri{background:rgba(88,166,255,.14);color:#9cccff}
.b-repro{background:rgba(227,179,65,.1);color:#e3b341}
.sev-crit{background:rgba(248,81,73,.18);color:#ff9a93}
.sev-major{background:rgba(240,136,62,.16);color:#f0a868}
.sev-minor{background:rgba(227,179,65,.14);color:#f0d080}
.sev-trivial{background:rgba(139,152,169,.14);color:#c7d0db}
.test{font-size:16px;font-weight:650;margin:11px 0 3px;color:var(--ink);line-height:1.4}
.feat{color:var(--mut);font-size:12.5px;margin-top:7px;font-weight:600}
.reason{color:var(--ink);font-size:13.5px;margin:8px 0 0;line-height:1.6}
.reason code{background:#0a0e14;border:1px solid var(--line);border-radius:4px;padding:1px 5px;font-size:12px}
details.report,details.trace{margin-top:11px}
details>summary{cursor:pointer;font-weight:600;font-size:12.5px;outline:none;
  list-style:none;display:inline-flex;align-items:center;gap:6px;padding:6px 12px;
  border:1px solid var(--line);border-radius:8px;background:var(--panel2);transition:.12s}
details>summary::-webkit-details-marker{display:none}
details>summary:hover{border-color:var(--mut2)}
details.report>summary{color:#9cccff}
details.trace>summary{color:var(--mut)}
details[open]>summary{margin-bottom:10px}
.report-body{border:1px solid var(--line);border-radius:10px;padding:4px 16px;background:rgba(10,14,20,.4)}
.sec{display:grid;grid-template-columns:175px 1fr;gap:16px;padding:12px 0;
  border-bottom:1px solid rgba(38,48,61,.55)}
.sec:last-child{border-bottom:none}
.sk{color:var(--mut);font-size:11px;text-transform:uppercase;letter-spacing:.5px;font-weight:700;padding-top:1px}
.sv{color:var(--ink);font-size:13.5px;line-height:1.65;min-width:0}
.sv p{margin:0 0 6px}.sv p:last-child{margin:0}
.sv ul,.sv ol{margin:0;padding-left:18px}.sv li{margin:4px 0}
.sv code{background:#0a0e14;border:1px solid var(--line);border-radius:4px;padding:1px 5px;
  font-size:12px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;word-break:break-word}
.sv a{color:#58a6ff;word-break:break-all}
.sv strong{color:#ff9a93}
.shot{max-width:100%;border-radius:8px;border:1px solid var(--line);display:block;max-height:560px}
details.trace pre{background:#0a0e14;border:1px solid var(--line);border-radius:8px;
  padding:12px;overflow:auto;font-size:11.5px;color:var(--mut);max-height:360px;
  font-family:ui-monospace,SFMono-Regular,Menlo,monospace;margin:0}
.foot{color:var(--mut2);font-size:12px;text-align:center;margin-top:40px;
  padding-top:20px;border-top:1px solid var(--line)}
.empty{color:var(--mut);text-align:center;padding:60px;font-size:16px}
@media(max-width:640px){.sec{grid-template-columns:1fr;gap:3px}.sk{padding-top:0}}
"""

JS = """
const q=document.getElementById('q'),chips=[...document.querySelectorAll('.chip[data-filter]')];
let filter='all';
function apply(){
  const t=q.value.trim().toLowerCase();
  document.querySelectorAll('.bug').forEach(b=>{
    const okF=filter==='all'||b.dataset.cls===filter;
    const okQ=!t||b.dataset.hay.includes(t);
    b.style.display=(okF&&okQ)?'':'none';
  });
  document.querySelectorAll('.grp').forEach(h=>{
    let n=h.nextElementSibling,any=false;
    while(n&&n.classList.contains('bug')){if(n.style.display!=='none')any=true;n=n.nextElementSibling;}
    h.style.display=any?'':'none';
  });
}
q.addEventListener('input',apply);
chips.forEach(c=>c.addEventListener('click',()=>{
  chips.forEach(x=>x.classList.remove('active'));c.classList.add('active');
  filter=c.dataset.filter;apply();
}));
const exp=document.getElementById('exp');
let open=false;
exp.addEventListener('click',()=>{
  open=!open;
  document.querySelectorAll('details.report').forEach(d=>d.open=open);
  exp.textContent=open?'⤡ Collapse all':'⤢ Expand all';
});
"""


def main():
    ap = argparse.ArgumentParser(description="Generate the CI bug-report HTML index.")
    ap.add_argument("--out", default=str(DEFAULT_OUT), help="output HTML path")
    ap.add_argument("--open", action="store_true", help="open the result in a browser")
    args = ap.parse_args()

    ctx = gather()
    page, total, product = render(ctx)
    out = Path(args.out)
    out.write_text(page, encoding="utf-8")
    b = f"#{ctx['build']}" if ctx.get("build") else ctx.get("result", "")
    print(f"Wrote {out}  ({total} confirmed bugs, build {b})")
    if args.open:
        webbrowser.open(out.resolve().as_uri())


if __name__ == "__main__":
    main()
QA_IO_VN_EOF

cat > "toolkit/_bugfile.py" <<'QA_IO_VN_EOF'
#!/usr/bin/env python3
"""Shared reader/writer for bugs/bug-NNN.md files (stdlib only).

Each bug file is a Markdown doc: a simple ``KEY: value`` frontmatter block fenced
by ``---`` lines, followed by the full bug-ticket body. Values are single-line; on
read every frontmatter line is split on its FIRST ``:`` so a title that itself
contains ``:`` (e.g. ``Feature: symptom``) is preserved intact.

Kept alongside _envfile.py so bugs_split.py and bug_log.py don't each re-implement
the same parse/serialize logic.
"""
from pathlib import Path

FENCE = "---"

# Canonical field order for a stable, diff-friendly frontmatter block. Unknown
# keys are appended in insertion order after these.
FIELD_ORDER = [
    "id",
    "source_test",
    "title",
    "system",
    "severity",
    "priority",
    "build",
    "generated",
    "status",
    "jira_key",
    "jira_url",
    "jira_logged_at",
    "jira_sprint",
]


def parse(path):
    """Return ``(frontmatter dict, body str)``. A missing file yields ``({}, "")``."""
    p = Path(path)
    if not p.exists():
        return {}, ""
    text = p.read_text(encoding="utf-8")
    if not text.startswith(FENCE):
        return {}, text
    lines = text.splitlines()
    end = None
    for i in range(1, len(lines)):
        if lines[i].strip() == FENCE:
            end = i
            break
    if end is None:
        return {}, text
    fm = {}
    for ln in lines[1:end]:
        if not ln.strip() or ":" not in ln:
            continue
        k, v = ln.split(":", 1)
        fm[k.strip()] = v.strip()
    body = "\n".join(lines[end + 1:]).lstrip("\n")
    return fm, body


def dump(fm, body):
    """Serialize frontmatter (canonical order, extras appended) + body to text."""
    keys = [k for k in FIELD_ORDER if k in fm] + [k for k in fm if k not in FIELD_ORDER]
    out = [FENCE]
    for k in keys:
        v = fm.get(k, "")
        out.append(f"{k}: {'' if v is None else v}")
    out.append(FENCE)
    out.append("")
    out.append((body or "").rstrip("\n"))
    out.append("")
    return "\n".join(out)


def write(path, fm, body):
    """Write ``dump(fm, body)`` to ``path`` (utf-8)."""
    Path(path).write_text(dump(fm, body), encoding="utf-8")
QA_IO_VN_EOF

cat > "toolkit/_envfile.py" <<'QA_IO_VN_EOF'
#!/usr/bin/env python3
"""Tiny shared .env reader for the ci/ tooling (stdlib only).

Parses KEY=VALUE lines, ignoring blanks and #comments and stripping surrounding
quotes — the same minimal format triage.py already uses for .claude/jenkins.env.
Kept here so jira.py and teams.py don't each re-implement it.
"""
from pathlib import Path


def load_env(path):
    """Read a KEY=VALUE env file into a dict. A missing file returns {}."""
    p = Path(path)
    if not p.exists():
        return {}
    cfg = {}
    for line in p.read_text().splitlines():
        line = line.strip()
        if not line or line.startswith("#") or "=" not in line:
            continue
        k, v = line.split("=", 1)
        cfg[k.strip()] = v.strip().strip('"').strip("'")
    return cfg


def require(cfg, *keys):
    """Return the listed values in order; exit with a clear error if any is blank."""
    missing = [k for k in keys if not cfg.get(k)]
    if missing:
        raise SystemExit(
            "Missing required key(s): "
            + ", ".join(missing)
            + ". Fill them into the matching .claude/*.env file."
        )
    return [cfg[k] for k in keys]
QA_IO_VN_EOF

cat > "toolkit/jira.env.example" <<'QA_IO_VN_EOF'
# Jira Cloud REST v3 credentials for ci/jira.py and the /verify-bug + /bug commands.
# Copy this file to .claude/jira.env (which is gitignored) and fill in real values.
# Do NOT put a real API token in this committed example.

# Your Atlassian site, no trailing slash.
JIRA_BASE=https://yourcompany.atlassian.net

# The account the API calls run as.
JIRA_EMAIL=you@company.com

# API token: https://id.atlassian.com/manage-profile/security/api-tokens
JIRA_TOKEN=

# Project key. Used to build the open-bugs query when `search` runs without
# --jql / JIRA_JQL_OPEN, e.g.:
#   project = <KEY> AND issuetype = Bug AND statusCategory != Done ORDER BY updated DESC
# REQUIRED for /bug: issue creation and active-sprint auto-detection both key off it
# (the scrum board + its active sprint are discovered from this project key alone).
JIRA_PROJECT=

# Optional: a full JQL string for `search` (takes precedence over the project default).
JIRA_JQL_OPEN=
QA_IO_VN_EOF

cat > "toolkit/teams.env.example" <<'QA_IO_VN_EOF'
# Teams Power Automate Workflow URL for ci/teams.py.
# Copy this file to .claude/teams.env (which is gitignored) and fill in the real URL.
#
# How to get the URL (no Azure app registration needed):
#   1. In Teams, open the target channel -> ... (More options) -> Workflows.
#   2. Pick the template "Post to a channel when a webhook request is received".
#   3. Finish the wizard; it generates an HTTPS POST URL — paste it below.
# The flow accepts an Adaptive Card payload (ci/teams.py sends exactly that shape).

TEAMS_WORKFLOW_URL=
QA_IO_VN_EOF

echo "Done. Installed into ./$TARGET:"
echo "  rules/PROJECT-INSTRUCTIONS-TEMPLATE.md  -> copy to your repo as CLAUDE.md (or equivalent) and fill in the placeholders"
echo "  commands/*.md                           -> copy to .claude/commands/ in your repo"
echo "  toolkit/*                                -> copy to ci/ in your repo, then fill in .claude/*.env from the .env.example files"
echo "  WORKFLOW.md, ADOPTION.md, TODO.md        -> read these next; ADOPTION.md is the setup checklist"
echo
echo "Next: open ADOPTION.md (or the Getting Started guide on qa.io.vn) and start at Level 1 -- dry-run only, nothing to approve yet."
Copied to clipboard
macOS, Linux, WSL, or Git Bash. On native PowerShell, run it inside Git Bash or WSL instead. Safe to re-run.
Chapter Two
The lifecycle

One rulebook, seven commands, shared state. Every outward action sits behind a gate.
Fig. 1The lifecycle. Solid tracks carry the work; nothing crosses a filled marker without meeting its condition.
gate — an outward action waits behind it
station
durable artifact
weekly cadence
The commands communicate through durable artifacts — a local bug store, a recurrence registry of known failures, manual test charters, and the tracker itself. Each command also states what it does not do: /ci never files Jira issues, /bug never re-triages, /manual-test writes no test code.
Chapter Three
The seven commands

A quick-reference spread: each entry names its stage, its work, and the gate that holds it.
/createAuthor coverage
From a dev ticket to automated tests: maps each acceptance criterion to the lowest sufficient layer, inspects the live product before writing a selector, tracks the work as a linked task.
Gate every new test green — 3× for UI.
/manual-testManual testing
Designs a manual test charter from the ticket's acceptance criteria, executes every case against the live product, records PASS/FAIL/BLOCKED with evidence, comments the result sheet on the ticket.
Gate advance to Done only when every case passes.
/verifyDelivery check
Audits whether automation actually asserts the ticket's expected result — a stale mapping counts as no coverage — authors what's missing, then closes the ticket.
Gate N clean runs (default 3), reruns off.
/verify-bugBug re-check
Re-runs a bug's mapped test; on stable green auto-advances the bug through the workflow to Done and posts the verdict.
Gate stable green of the mapped test.
/ciCI triage
Pulls the failed build, triages every failure on its own merits with the known-failures registry as a prior, fixes test bugs, writes ISTQB-style product-bug tickets.
Gate fixes count only when locally green; extended mode adds 3× + full suite.
/bugFile defects
Files the bug store into Jira — active sprint, mapped priority, idempotent. The one command that always asks before writing.
Gate interactive confirm.
/reportWeekly report
Reconstructs the week from the git diff, not commit messages, into one plain-English paragraph. Undercounts when unsure.
Gate counts must trace to the diff.
Chapter Four
The seven pillars

Inspect before you assert
Selectors and contracts come from the live product, never guessed from a similar page.
Test at the lowest sufficient layer
E2E only for what a browser alone can prove.
Page Object discipline
One page per class, constants not magic strings, fluent API.
Deterministic waiting
Hardcoded sleeps forbidden; every wait names its condition.
Tests own their data
Seed, assert, clean up; leave the environment as found.
The stable-green gate
Nothing closes on one lucky pass; reruns-off, three consecutive greens by default.
Honesty over green
Blocked is a legitimate verdict; a false PASS is worse than an honest FAIL.
Chapter Five
Adopt it

A working skeleton takes about a day.
Write the project rulebook
Stand up the connectorsJira, Teams, CI; gitignored env files.
Map your tracker workflow once
Create the token-saving live-inspection reference
Install the commandskeep the gates verbatim.
Start the shared state emptynever seed the registry with assumptions.
Dry-run the loop end to endbefore trusting standing authorizations.
Read the adoption guide
Also on the shelf: commands/· toolkit/· rules/PROJECT-INSTRUCTIONS-TEMPLATE.md