@roopesh.yadava/qa-pack 1.4.0 → 1.5.1

package/README.md

@@ -92,12 +92,26 @@ and `/write-acceptance-criteria`, which are also available as explicit slash com
 | `/write-acceptance-criteria PROJ-123` | write-acceptance-criteria | Generates AC, appends to the Jira card description |
 | `/impacted-tests` / `which tests are impacted by this pull` | impacted-tests | After pulling dev changes into a test branch, reports which Cucumber feature files are at risk — report-only, no card needed |
 | `set up k6` / `scaffold performance tests` | k6-framework-scaffold | Scaffolds a `k6-performance-tests/` framework (Grafana Cloud, protocol + optional browser layers) with commented templates to fill in — no card needed |
+| `roam mode` / `explore the app` | roam-testing | Card-free exploratory testing — capped breadth-first crawl, report + optional bug filing + charter |
+| `qa dashboard` / `weekly digest` / `token roi` | qa-insights | Cross-product health dashboard, weekly digest, or token-spend/ROI view — 100% script-generated, no card needed |
+
+## The toolkit — why these features stay cheap
+
+Several features above (self-improving locator memory, DOM fingerprint caching, duplicate-bug
+detection, PII/secrets scanning, risk-based test ordering, the trust ratchet, and every
+`qa-insights` report) are powered by one dependency-free script:
+`.claude/skills/qa-agent/toolkit/qa-toolkit.cjs`. Skills shell out to it and read back a
+single line — parsing markdown tables, hashing DOM snapshots, scoring bug-title similarity,
+and aggregating every product's history are pure computation, so none of it costs a model
+token beyond the one line of output. This is also why `qa-insights` (dashboard/digest/ROI
+across every product you've ever tested) costs about the same whether you have 2 products or
+200 — the script does the aggregation, not the model.
 
 ## What postinstall does
 
 | File | Behaviour |
 |---|---|
-| `.claude/skills/*/SKILL.md` + companion `.md` files | Always overwritten (versioned logic) |
+| `.claude/skills/*/SKILL.md` + companion `.md`/`.cjs`/`.sh` files (e.g. the toolkit script) | Always overwritten (versioned logic) |
 | `.claude/skills/SKILLS_CONTEXT.md` | Always overwritten + stamped with the installed pack version |
 | `.claude/commands/*.md` | Always overwritten |
 | `.claude/skills/qa-agent/product_context/**` | **Never touched** after first seed |

package/claude/skills/SKILLS_CONTEXT.md

@@ -50,6 +50,8 @@ A 10-test run with `browser_snapshot()` per test = ~100k wasted tokens.
 | `BDD_TEMPLATES.md` | Once at Phase 1 start | Never reload in the same run |
 | `LOCATOR_PATTERNS.md` | Once at Phase 1 start | Never reload in Phase 2 or 3 |
 | `WCAG_CHECKS.md` | Once at skill start | Never reload |
+| `manual-testing/TEST_DESIGN_GUIDE.md` | Once at Phase 1c (manual-testing) | Never reload — reference sections by number (§1–§9) |
+| `mobile-automation/MOBILE_MCP_REFERENCE.md`, `BDD_TEMPLATES.md`, `LOCATOR_PATTERNS.md` | Once at Phase 2 start (mobile-automation) | Never reload in Phase 3 or 4 |
 | `test-charter.md` | Once when charter starts | Never reload |
 | `context.md` | Once at qa-agent Step 0 | Never reload |
 
@@ -70,6 +72,45 @@ Structure every skill invocation in this order so the stable prefix can be cache
 The stable block qualifies for Anthropic prompt caching when it exceeds 1024 tokens.
 Cache TTL is 5 minutes. Keep the stable block identical across runs for the same product.
 
+### The Toolkit — the low-token path for anything product_context-shaped
+
+`.claude/skills/qa-agent/toolkit/qa-toolkit.cjs` is a dependency-free Node script, not a
+skill. It exists because parsing a markdown table, hashing a DOM snapshot, scoring string
+similarity, or aggregating dozens of products' history is pure computation — routing it
+through the model (Read the file → reason over it → maybe Edit it back) burns tokens on work
+that doesn't need a model at all. **Any skill needing one of the things below calls the
+toolkit and reads only its one-line result — never Read a whole context.md for this.**
+
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs <command> [--flags]
+```
+
+| Command | Used by | Purpose |
+|---------|---------|---------|
+| `get-bugs` / `get-runs` / `get-selectors` --product P | any skill | Cheap reads of one context.md table, pipe-delimited rows |
+| `fingerprint` --product P --url U --testids "a,b" | manual-testing, automation, mobile-automation, roam-testing | DOM/screen fingerprint cache — `UNCHANGED` means skip re-discovery. Mobile uses a synthetic `mobile:{bundleId}/{Screen}` string as `--url` and resource-id/accessibility-id values as `--testids` — the command itself is platform-agnostic |
+| `pii-scan` (stdin or `--file`) | bug-reporting, manual-testing, roam-testing | Flags emails/keys/tokens before anything is posted to Jira |
+| `dup-bug` --product P --summary S | bug-reporting, manual-testing, roam-testing | Fuzzy-matches a new bug against Known Bugs, no LLM comparison needed |
+| `cost-estimate` --product P [--phase N] | qa-agent | One-line run-cost estimate from Runs Log history |
+| `risk-score` --product P --modules "a,b" | manual-testing | Orders tests by git churn + past bug density, not AC order |
+| `trust-record` / `trust-status` --product P [--namespace N] | automation, mobile-automation (`--namespace mobile` — routes to a separate `trust.mobile.json` so its gate streaks never enter qa-agent's web-only eligibility computation), qa-agent (status) | Trust ratchet on Gate 1/Gate 2 approvals. `--namespace` is optional and additive — omitted, behavior is unchanged (`trust.json`); `trust-status` takes `min(streak)` across every gate in whichever file it reads, so gates from two automation surfaces must never share one file |
+| `locator-record` / `locator-query` --product P --page U | automation, mobile-automation (page keys prefixed `mobile:` to avoid colliding with web page URLs) | Self-improving locator memory across self-heal fixes |
+| `dashboard` / `digest [--days N]` / `roi` | qa-insights | Cross-product reports — 100% script-generated, zero synthesis. Add `--json` to any of the three for a structured payload (same data, machine-readable) instead of the one-line summary — for anything scripting against this (e.g. an external dashboard app) rather than chatting with it. |
+
+This file is versioned logic (always overwritten on `npm update`, like every other skill
+file) — never store product data inside it. Its outputs live under
+`product_context/{PRODUCT}/` (`dom-fingerprints.json`, `trust.json`,
+`locator-learnings.md` — all new, all gitignored the same way `context.md` already is) or
+`outputs/` (`dashboard.html`, `qa-weekly-digest-*.md`, `roi-report.md`).
+
+**Never inline arbitrary text into a toolkit shell call.** Bug descriptions, locator
+strings, and anything else that isn't a short agent-controlled token (a card ID, a product
+folder name, a URL) can contain quotes, `` ` ``, `$(...)`, or `|` — inlined into a bash
+argument, that is a command-injection bug, not just an escaping nuisance. Write the text to
+a file with the Write tool first and pass the path: `pii-scan --file`, `dup-bug
+--summary-file`, `locator-record --file <json>`. Only short, structurally-constrained values
+(URLs, card IDs, product folder names) are safe to inline directly.
+
 ---
 
 ## Pipeline Overview
@@ -105,25 +146,38 @@ test-charter   │
     End-to-End Testing complete
 ```
 
+`roam-testing` (card-free exploratory) and `qa-insights` (dashboard/digest/roi) sit outside
+this diagram — they don't take a Jira card, and qa-insights doesn't touch Playwright at all.
+Both are driven by the toolkit rather than by each other.
+
+`mobile-automation` also sits outside this diagram — it's a standalone, directly-triggered
+skill (same status as `roam-testing`/`k6-framework-scaffold`), not wired into qa-agent's
+Phase 2 dispatch, which remains web/Playwright-only via `automation`. Trigger it by name
+("automate mobile PROJ-123", "mobile test PROJ-123") rather than through the qa-agent phase menu.
+
 ## Skills — One-Line Summary
 
 | Skill | Input | Output | MCP Needed |
 |-------|-------|--------|------------|
 | `qa-agent` | Jira card ID or menu choice | Dispatches to correct skill | Atlassian |
 | `automation` | Jira card ID | Reuse audit + Gherkin + Step Defs + POM + real run (reuse % reported) | Atlassian, Playwright |
+| `mobile-automation` | Jira card ID | Reuse audit + mobile Gherkin + Step Defs + Screen POM + real device run (reuse % reported) | Atlassian, Mobile MCP, MobileWright/mobilecli |
 | `manual-testing` | Jira card ID + app URL | Execution report + bugs + charter | Atlassian, Playwright |
 | `ui-test-figma` | Figma URL + app URL | UI mismatch report, Jira comment | Playwright (CLI+MCP), Figma (optional) |
 | `accessibility-testing` | Full page URL + Jira card (optional) | WCAG 2.1 A/AA report + Jira bugs | Playwright (CLI+MCP), Atlassian |
 | `bug-reporting` | Bug description | Bug filed on Jira card | Atlassian |
 | `test-charter` | Execution report MD file | Charter MD + published to API | Playwright (login) |
+| `roam-testing` | App URL, no card required | Roam report + optional bugs + charter | Playwright, Atlassian (optional) |
+| `qa-insights` | Nothing (reads all products) | Dashboard HTML / digest MD / ROI MD | None — pure toolkit |
 
 ## God Nodes (highest connectivity — touch these carefully)
 
-1. `automation` — 13 edges (Gherkin→StepDefs→POM chain, token tracking, Playwright MCP)
-2. `manual-testing` — 12 edges (orchestrates ui-test-figma, bug-reporting, test-charter)
-3. `qa-agent` — 7 edges (dispatches all paths, owns the Phase 3 pipeline)
-4. `test-charter` — 6 edges (reads execution report, publishes to Decision Record API)
-5. `ui-test-figma` — 6 edges (Figma MCP preferred, Playwright CLI fallback)
+1. `automation` — 15 edges (Gherkin→StepDefs→POM chain, token tracking, Playwright MCP, locator memory, trust ratchet)
+2. `manual-testing` — 15 edges (orchestrates ui-test-figma, bug-reporting, test-charter, risk-score, fingerprint, dup-bug)
+3. `qa-toolkit.cjs` — 6 skills call into it (qa-agent, automation, manual-testing, bug-reporting, roam-testing, qa-insights) — not a skill itself, but the single highest-fan-in file in the pack
+4. `qa-agent` — 9 edges (dispatches all paths, owns the Phase 3 pipeline, cost estimate + trust status)
+5. `test-charter` — 7 edges (reads execution report, publishes to Decision Record API; also used by roam-testing)
+6. `ui-test-figma` — 6 edges (Figma MCP preferred, Playwright CLI fallback)
 
 ## Dispatch Map (qa-agent routes)
 
@@ -135,6 +189,8 @@ Phase 3 / "full QA"        → manual-testing THEN automation (hints file reused
 "accessibility test"       → accessibility-testing (standalone, URL + optional Jira card)
 "file bug"                 → bug-reporting   (standalone)
 "charter"                  → test-charter    (standalone)
+"roam mode" / "explore"    → roam-testing    (standalone, no card — routed outside qa-agent)
+"dashboard"/"digest"/"roi" → qa-insights     (standalone, no card — routed outside qa-agent)
 ```
 
 **Input collection happens ONCE in qa-agent.** Sub-skills receive their parameters in the
@@ -196,6 +252,7 @@ python3 $PROJECT/track_tokens.py session
 
 **Phase names by skill:**
 - automation: `start` → `jira_fetch` → `reuse_audit` → `gherkin_generation` → `step_definitions` → `pom_generation` → `test_run` → `end`
+- mobile-automation: `start` → `jira_fetch` → `reuse_audit` → `gherkin_generation` → `step_definitions` → `pom_generation` → `test_run` → `end`
 - manual-testing: `start` → `jira_fetch` → `ui_testing` → `test_execution` → `end`
 - ui-test-figma: `start` → `login` → `comparison` → `end`
 - accessibility-testing: `start` → `login` → `a11y_checks` → `end`
@@ -232,7 +289,17 @@ First run will always be 0% (cold cache). Second and subsequent runs should cach
 | Auth session | `.playwright-session.json` (gitignored) |
 | Secrets / environment | `.env` at repo root (gitignored) |
 | Step catalog (reuse audit) | `.claude/skills/qa-agent/product_context/[PRODUCT]/step-catalog.md` |
+| Mobile step catalog (reuse audit) | `.claude/skills/qa-agent/product_context/[PRODUCT]/mobile-step-catalog.md` |
 | Automation hints | `outputs/automation-hints-[CARD]-[date].md` |
 | Token analytics | `~/.claude/token_analytics.png` |
 | Knowledge graph | `graphify-out/graph.html` (open in browser) |
 | Product QA context | `.claude/skills/qa-agent/product_context/[PRODUCT]/context.md` |
+| DOM fingerprint cache | `.claude/skills/qa-agent/product_context/[PRODUCT]/dom-fingerprints.json` |
+| Trust ratchet state | `.claude/skills/qa-agent/product_context/[PRODUCT]/trust.json` |
+| Locator learnings | `.claude/skills/qa-agent/product_context/[PRODUCT]/locator-learnings.md` |
+| Roam session report | `outputs/roam-report-[timestamp].md` |
+| Product health dashboard | `outputs/dashboard.html` |
+| QA weekly digest | `outputs/qa-weekly-digest-[date].md` |
+| Token-spend / ROI view | `outputs/roi-report.md` |
+| Shared toolkit CLI | `.claude/skills/qa-agent/toolkit/qa-toolkit.cjs` |
+| Manual-testing coverage/scenario reference | `.claude/skills/manual-testing/TEST_DESIGN_GUIDE.md` |

package/claude/skills/automation/SKILL.md

@@ -269,14 +269,21 @@ Present Gherkin + reuse report and ask:
 >
 > **Type "looks good" or "confirmed" to proceed to step definitions.**
 
-Do not write any `.cjs` files until confirmed. Iterate until approved.
+Do not write any `.cjs` files until confirmed. Iterate until approved. Once approved, record
+the trust ratchet — `clean` if the user approved on first presentation with no revision
+requests this gate, `edited` if they asked for any change before approving:
+
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs trust-record --product {PRODUCT_FOLDER} --gate gate1 --result clean|edited
+```
 
 **If AUTO_APPROVE = true (called from qa-agent full pipeline):**
 
 Display the reuse report + a compact summary — do NOT wait:
 > "Gherkin generated for [CARD-ID]: {N} Rules, {N} scenarios, {X}% step reuse. Auto-approved — proceeding to step definitions."
 
-Immediately move to Phase 2 without waiting for any input.
+Immediately move to Phase 2 without waiting for any input. Do not call `trust-record` here —
+there was no human review to score.
 
 After either path: run `gherkin_generation` token checkpoint, then move to Phase 2.
 
@@ -329,14 +336,19 @@ Present step definitions and ask:
 >
 > **Type "looks good" or "confirmed" to proceed to the POM.**
 
-Do not write the POM until confirmed.
+Do not write the POM until confirmed. Once approved, record the trust ratchet the same way
+as Gate 1:
+
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs trust-record --product {PRODUCT_FOLDER} --gate gate2 --result clean|edited
+```
 
 **If AUTO_APPROVE = true (called from qa-agent full pipeline):**
 
 Display a compact summary only — do NOT wait:
 > "Step definitions generated for [CARD-ID]: {N} steps across {N} files. Auto-approved — proceeding to POM."
 
-Immediately move to Phase 3 without waiting for any input.
+Immediately move to Phase 3 without waiting for any input. Do not call `trust-record` here.
 
 After either path: run `step_definitions` token checkpoint, then move to Phase 3.
 
@@ -356,7 +368,31 @@ class. Only create a new POM class for a page that has none.
 Use the POM class template from BDD_TEMPLATES.md for new classes; match the existing
 class's style when extending.
 
-For every locator:
+**Locator memory check — once per page, before opening Playwright MCP for it:**
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs locator-query --product {PRODUCT_FOLDER} --page "PAGE_URL"
+```
+`NONE` → nothing learned yet for this page, proceed as usual. Rows returned → for each
+listed element, avoid its recorded **Failed Locator** even if it looks like the obvious
+choice; that pattern already broke a real test on this page. Prefer its recorded **Working
+Locator** if the element matches.
+
+**DOM fingerprint check — once per distinct page URL this run:**
+```javascript
+browser_evaluate({ expression: `
+  Array.from(document.querySelectorAll('[data-testid]')).map(el => el.getAttribute('data-testid')).join(',')
+` })
+```
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs fingerprint --product {PRODUCT_FOLDER} --url "PAGE_URL" --testids "RESULT_FROM_ABOVE"
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs get-selectors --product {PRODUCT_FOLDER} --url "PAGE_URL"
+```
+If fingerprint says `UNCHANGED` and `get-selectors` returns rows covering the elements this
+Rule needs, write the POM locators straight from those rows — skip the per-element DOM
+inspection below entirely for this page. Otherwise (`NEW`/`CHANGED`, or a needed element is
+missing from `get-selectors`) fall through to the full inspection:
+
+For every locator not already resolved above:
 1. Navigate to the real page in the live app via Playwright MCP
 2. Inspect the target element in the DOM
 3. Check if `data-testid` already exists
@@ -420,7 +456,18 @@ On failure, diagnose and fix — **never hand off a silently failing test**:
 
 1. Read the failure: locator timeout? assertion mismatch? navigation/auth issue?
 2. Locator failures → re-inspect that element via Playwright MCP, fix the POM locator
-   (respect the locator priority table).
+   (respect the locator priority table). Once the fix passes, record it so no future run on
+   this product repeats the same wrong guess. Locator strings routinely contain quotes and
+   `|` (xpath unions) — never inline them into a shell command; write a small JSON file
+   instead (Write tool) and pass its path:
+   ```
+   Write outputs/.locator-tmp.json containing:
+   {"product": "{PRODUCT_FOLDER}", "page": "PAGE_URL", "element": "ELEMENT_LABEL",
+    "failed": "OLD_LOCATOR", "fixed": "NEW_LOCATOR", "reason": "ONE_LINE_WHY", "card": "{CARD_ID}"}
+   ```
+   ```bash
+   node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs locator-record --file outputs/.locator-tmp.json
+   ```
 3. Assertion failures → check whether expected text/behavior on the card matches the app.
    If the app appears genuinely wrong, this is a **bug, not a test fix** — stop healing
    that scenario, mark it failing, and note it as a bug candidate in the hand-off.

package/claude/skills/bug-reporting/SKILL.md

@@ -27,6 +27,12 @@ Display the list and ask:
 
 Wait for the user to select a project by number or board key. Save the selected project key for the rest of the flow.
 
+**Resolve `PRODUCT_FOLDER` (best-effort — only used by the duplicate check in Step 2a):**
+check whether `.claude/skills/qa-agent/product_context/{KEY}/context.md` exists, or any
+folder under `product_context/` starts with `{KEY}`. Found → store as `PRODUCT_FOLDER`.
+Not found → leave `PRODUCT_FOLDER` unset and skip the duplicate half of Step 2a silently;
+this is not an error, most exploratory-bug filing has no prior product context yet.
+
 ---
 
 ## Step 1A/1B — Ask card type
@@ -110,6 +116,38 @@ Do NOT ask the user for any missing fields. Use what was given and proceed.
 
 ---
 
+## Step 2a — Duplicate + PII/secrets check (script calls, no extra questions unless flagged)
+
+The user typed this text freely — it can contain quotes, `$`, backticks, anything. **Never**
+interpolate it directly into a shell command; write it to a file with the Write tool first
+and pass the file path instead.
+
+**Duplicate check — only if `PRODUCT_FOLDER` was resolved in Step 1:**
+```
+Write outputs/.dupcheck-tmp.txt containing: {Bug Title}
+```
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs dup-bug --product {PRODUCT_FOLDER} --summary-file outputs/.dupcheck-tmp.txt
+```
+`NO_DUPLICATE_FOUND` → proceed silently. `POSSIBLE_DUPLICATE: {BUG-ID} (...) — "{title}"` →
+mention it once above the formatted report in Step 3: `"Heads up — this looks similar to
+{BUG-ID}: \"{title}\" ({status}). File as a new bug anyway, or add to that one instead?"`
+Follow whichever the user picks.
+
+**PII/secrets scan — always, regardless of PRODUCT_FOLDER:**
+```
+Write outputs/.piicheck-tmp.txt containing: {Bug Title}\n{Expected Outcome}\n{Actual Outcome}\n{Steps to Reproduce}
+```
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs pii-scan --file outputs/.piicheck-tmp.txt
+```
+Delete both temp files once this bug is posted (Step 6). `CLEAN` → proceed silently.
+`FLAGGED: ...` → show the flagged pattern types (never the raw
+match) and ask once: `"This bug report may contain real {types}. Redact before posting, or
+file as-is? (redact / as-is)"`. Apply the choice, then continue to Step 3.
+
+---
+
 ## Step 3 — Display the formatted bug report
 
 Show the bug report in this exact format before posting:

package/claude/skills/manual-testing/SKILL.md

@@ -2,8 +2,12 @@
 name: manual-testing
 description: >
   Manual Testing branch orchestrator. Follows the flowchart:
-  Jira Card Input → UI Testing (Figma MCP, optional) → Manual Testing (Playwright MCP)
-  → Bug Reporting (Atlassian MCP) → Test Charter → Automation Agent (optional handoff).
+  Jira Card Input → Requirement Gap Analysis → UI Testing (Figma MCP, optional) →
+  Manual Testing (Playwright MCP) → Bug Reporting (Atlassian MCP) → Test Charter →
+  Automation Agent (optional handoff).
+  Test planning is risk-scoped and coverage-dimension-driven (see TEST_DESIGN_GUIDE.md) —
+  not just "1-3 tests per AC line" — so a payment/auth card gets materially deeper coverage
+  than a copy-change card.
   Captures element selectors and interaction data during execution and saves them to an
   automation-hints file for the automation skill to reuse — skipping DOM re-discovery.
   Uses Playwright CLI for zero-token screenshots. Token tracking enabled.
@@ -95,6 +99,17 @@ Use `getJiraIssue` to fetch `CARD_ID`. Extract and store:
 - `FIGMA_URL_FROM_CARD` — any Figma link found in description or comments
 - `PROJECT_KEY` — for bug filing later
 
+Derive `PRODUCT_FOLDER` now (uppercase `PROJECT_KEY`'s product name, spaces → `_` — same
+normalisation qa-agent Step 6a uses) so Phases 3 and 4 below can call the toolkit without
+re-deriving it. If the qa-agent parameter block already named a product folder, use that instead.
+
+If a product folder was resolved, pull known bugs cheaply for the retest check used in 3a/§9
+— one script call, not a `context.md` read:
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs get-bugs --product {PRODUCT_FOLDER}
+```
+Store non-`Closed`/`Done` rows as `OPEN_KNOWN_BUGS`. `NO_CONTEXT_FILE`/`NO_BUGS` → `OPEN_KNOWN_BUGS = []`, first run for this product.
+
 Run token tracking `jira_fetch` checkpoint.
 
 ### 1b — Truncate Jira data if card is verbose
@@ -108,14 +123,33 @@ After fetching, check `CARD_DESCRIPTION` length:
 
 Do NOT tell the user the description was truncated. This prevents verbose cards from consuming 5k+ tokens before testing even starts.
 
-If no AC found (and qa-agent didn't already resolve this):
-> "No Acceptance Criteria found on this card. What should be tested?"
-Wait for user response before continuing.
-
 Set from Phase 0 values (all input was collected there — do not re-ask):
 - `RUN_UI_TEST` — true when a Figma URL is available (from parameter block, card, or user)
 - `FIGMA_URL`, `APP_URL`, `USERNAME`, `PASSWORD`, `OTP_CODE`
 
+### 1c — Load Test Design Guide (once)
+
+Read `.claude/skills/manual-testing/TEST_DESIGN_GUIDE.md` now. Per the Static File Load
+Rules in `SKILLS_CONTEXT.md`, load it once here and never reload it later in this run —
+reference its sections by number (e.g. "per §4 High risk") for the rest of the pipeline.
+
+### 1d — Requirement Gap Analysis
+
+Run the checklist in `TEST_DESIGN_GUIDE.md` §1 against `CARD_TITLE` + `ACCEPTANCE_CRITERIA`.
+This **replaces** the old bare "no AC found" check — the missing-AC row is §1's first row and
+is the most severe: if it fires, skip evaluating the rest of the table and ask only that.
+
+Fold every gap that actually applies into **one** consolidated question — the same message as
+any unresolved Phase 0 gaps, not a second round:
+> "No Acceptance Criteria found on this card. What should be tested?" (only if AC is entirely
+> missing), or, when AC exists but has gaps: one line per applicable §1 row, e.g. "AC mentions
+> a 'reference code' but doesn't state its length/format — what's the exact rule?"
+
+Skip this step's question entirely if the AC is already precise and complete on every §1
+row — do not manufacture questions to fill the message.
+
+Wait for the response before proceeding to Phase 2.
+
 ---
 
 ## Phase 2 — UI Testing (optional)
@@ -158,21 +192,58 @@ HINTS = {
 }
 ```
 
-### 3a — Generate Test Plan
+### 3a — Generate Test Plan (risk-scoped, coverage-dimension-driven)
 
 Before drafting test ideas, check each AC item for a stated entry point (menu path, URL,
 button/link name). Per the **Test Data & Entity Selection Rules** above, do not scan `src/`
 to infer a missing one — collect a single navigation question per missing entry point and
 fold it into the confirmation prompt below instead of guessing.
 
-From the AC, generate numbered test ideas:
-- 1–3 tests per AC item
-- 2+ negative/edge case tests
-- 1+ error state test
+**Step 1 — Classify risk tier and select dimensions.** Using `TEST_DESIGN_GUIDE.md` §2 (Feature
+Signal → Coverage Dimension Trigger Table), scan `CARD_TITLE` + `ACCEPTANCE_CRITERIA` for
+signal keywords and turn on the matched dimensions. No signal matched → default set only
+(Functional Positive/Negative + UI/UX States + one Boundary check). Then classify the card's
+risk tier per §4 (High/Medium/Low) from the same signals — this sets how many tests each
+triggered dimension gets, not just which dimensions run.
+
+**Step 2 — Draft numbered test ideas per dimension.** Walk the §5 Test Scenario Identification
+Framework (the 10 "what can/can't/who/what happens" questions) once, and for each dimension
+turned on in Step 1, draft the number of tests §4's tier calls for. Concretely, for a Medium-risk
+card this typically looks like: 1–2 Functional Positive, 1–2 Functional Negative, one Boundary
+or Equivalence set per §6 if the AC states or implies a limit, one UI/UX States pass (§8) on the
+card's key screen, plus one test per other triggered dimension (Permissions, API, Database,
+State/Workflow, etc.). High-risk cards double the per-dimension count and add Security-oriented
++ Database checks unconditionally per §4. Low-risk cards (copy/label-only) skip straight to
+Functional (positive + one negative) plus one regression spot-check — do not force the other
+dimensions onto a low-risk card.
+
+Cap exploratory ideas (§5 Q10) at one per plan, clearly tagged `[exploratory]`, so they don't
+inflate the "planned" test count used for the Exit Criteria check later (§9).
+
+If `OPEN_KNOWN_BUGS` (from Phase 1) contains a row whose Title overlaps this card's module/page
+keywords, add one retest test tagged `[retest: {BUG-ID}]` — this is what §9's retest check
+verifies actually happened.
+
+Do not draft dedicated regression tests here — that's qa-agent Step 5's job (Covered Flows
+overlap), triggered automatically after this skill returns. §5 Q9 exists only to flag *that*
+regression may apply, not to author it now.
+
+**Risk-based execution ordering** — pull 2–5 module/page keywords straight out of the AC/card
+title you already read (e.g. "login", "checkout"; no extra fetching), then run one script call:
+
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs risk-score --product {PRODUCT_FOLDER} --modules "kw1,kw2,kw3"
+```
 
-Show as a compact table (T-01, T-02 ... with name and expected outcome).
-Ask: `"Ready to run these tests? (yes / no or edit)"` — include any missing navigation
-questions in this same message.
+Order the T-01, T-02... list so tests touching the highest-risk module come first. On a
+product's first run (no git history / no known bugs yet) every module scores 0 — keep the
+natural drafting order in that case, no need to mention it. (This reorders the tests drafted in
+Step 2 — it doesn't decide how many exist; that's §4's job, run once, not repeated per module.)
+
+Show as a compact table (T-01, T-02 ... with name, dimension tag, and expected outcome),
+risk-ordered. Ask: `"Ready to run these tests? (yes / no or edit)"` — include any missing
+navigation questions from above in this same message (§1 gap questions were already asked
+and resolved in Phase 1d — don't re-ask them here).
 Proceed on confirmation.
 
 ### 3b — Setup Browser + Capture Login Selectors
@@ -241,6 +312,21 @@ For each test T-01, T-02, ...:
 1. Navigate to the feature area via Playwright MCP (preserves session)
 2. Add current URL to `HINTS.pages` if not already present
 
+2a. **DOM fingerprint check — once per distinct URL, the first time you land on it this run:**
+   ```javascript
+   browser_evaluate({ expression: `
+     Array.from(document.querySelectorAll('[data-testid]')).map(el => el.getAttribute('data-testid')).join(',')
+   ` })
+   ```
+   ```bash
+   node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs fingerprint --product {PRODUCT_FOLDER} --url "CURRENT_URL" --testids "RESULT_FROM_ABOVE"
+   ```
+   - `UNCHANGED` → this page's selectors haven't moved since a prior run. Skip step 3's
+     per-interaction element capture for this page entirely (still perform the actual test
+     interactions and assertions — only the *hint-recording* is skipped). Add one line to
+     `HINTS.notes`: `"Elements on {url}: unchanged — reused prior fingerprint, capture skipped."`
+   - `NEW` or `CHANGED` → proceed with full per-interaction capture in step 3 below, same as always.
+
 3. For each browser interaction (`browser_fill`, `browser_click`, `browser_select_option`):
    - Execute the interaction
    - Immediately run element capture (zero-token, targeted JS):
@@ -275,10 +361,13 @@ For each test T-01, T-02, ...:
      outputs/screenshots/T-[N]-[pass|fail|observation].png
    ```
 
-5. Assert expected result via targeted `browser_evaluate` on specific selectors
+5. Assert expected result via targeted `browser_evaluate` on specific selectors. If this
+   test's dimension tag (from 3a) is UI/UX States, note which of the `TEST_DESIGN_GUIDE.md`
+   §8 states (Initial/Loading/Empty/Success/Error/Disabled) were actually observed and their
+   result — skip states genuinely unreachable in this test, don't force them.
 
 6. Log test result (to file only, not chat):
-   `T-N | title | status | expected | actual | screenshot path`
+   `T-N | title | dimension | status | expected | actual | screenshot path`
 
 7. Append to `HINTS.testCases`:
    ```
@@ -346,7 +435,7 @@ Run token tracking `test_execution` checkpoint.
 
 After saving the automation hints file, silently update the product context.
 
-Derive `PRODUCT_FOLDER` from `PROJECT_KEY` fetched in Phase 1 (uppercase, spaces → `_`).
+`PRODUCT_FOLDER` was already derived in Phase 1 — reuse it, don't re-derive.
 
 ```
 CONTEXT_FILE = .claude/skills/qa-agent/product_context/{PRODUCT_FOLDER}/context.md
@@ -377,15 +466,56 @@ this keeps context contiguous and avoids a second skill invocation.
 
 **Step 4a — Build bug payload for each ❌ FAIL and ⚠️ OBSERVATION**
 
-Derive all fields from test execution data — no user input needed:
+Derive all fields from test execution data — no user input needed. Fields follow
+`TEST_DESIGN_GUIDE.md` §7:
 
 | Field | Source |
 |-------|--------|
 | Summary | `"T-{N}: {test name} — {actual outcome in one line}"` |
-| Description | Steps from test case + expected vs actual from execution log |
+| Environment | `APP_URL` + environment name from product context (staging/dev/prod) |
+| Preconditions | Login state + any setup steps from the test case (e.g. role, prior state) |
+| Description (Steps/Expected/Actual) | Steps from test case + expected vs actual from execution log |
 | Severity | AC explicitly failed → High · Assertion failed → Medium · Observation → Low |
+| Priority | High-risk dimension (§4) failing → High · otherwise matches Severity |
+| Test data used | The specific values/entities used for this test (never credentials) |
+| Build/version | `CARD_ID` + run date (stands in for a separate build number) |
 | Screenshot | Match `outputs/screenshots/T-{N}-*.png` by test ID — use exact filename |
 
+**Step 4a.1 — Duplicate check (one script call per failure, no user input needed)**
+
+Test names are derived from the AC, not typed by a person, but AC text copied from Jira can
+still contain quotes or symbols — never inline free text into a shell command. Write it with
+the Write tool first, then reference the file:
+
+```
+Write outputs/.dupcheck-tmp.txt containing: T-{N}: {test name}
+```
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs dup-bug --product {PRODUCT_FOLDER} --summary-file outputs/.dupcheck-tmp.txt
+```
+
+`NO_DUPLICATE_FOUND` → proceed normally. `POSSIBLE_DUPLICATE: {BUG-ID} (...) — "{title}"` →
+still file the bug (a regression is a real, separately-trackable failure) but prepend one
+line to the Description: `"⚠ Possibly related to {BUG-ID}: {title}"` for the triager.
+
+**Step 4a.2 — PII / secrets scan (one script call per bug, before it leaves the machine)**
+
+Same rule — the Description includes live-app text (error messages, field values) that can
+contain anything. Write it to a file, never interpolate it into the command:
+
+```
+Write outputs/.piicheck-tmp.txt containing the composed Summary + Description text
+```
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs pii-scan --file outputs/.piicheck-tmp.txt
+```
+
+`CLEAN` → proceed silently. `FLAGGED: ...` → this is rare (test data occasionally captures a
+real value) — pause only this one bug, show the flagged pattern types (never the raw match),
+and ask once: `"This bug's description may contain real {types}. Redact and continue, or file as-is? (redact / as-is)"`.
+Apply the user's choice, then continue to the next failure — do not stop the whole batch.
+Delete both `outputs/.dupcheck-tmp.txt` and `outputs/.piicheck-tmp.txt` once the batch is done.
+
 **Step 4b — File each bug via Atlassian MCP (parallelise where possible)**
 
 For each failure:
@@ -431,14 +561,22 @@ Run token tracking `end + report + session` close-out after charter publishes.
 
 ## Phase 6 — Automation Handoff
 
-After charter completes, show the final summary:
+After charter completes, run the `TEST_DESIGN_GUIDE.md` §9 Exit Criteria Quick Check:
+confirm every planned test executed (BLOCKED is fine, silently-skipped is not), check whether
+any bug just filed is High severity on a High-risk dimension (§4) and if so flag it as the
+first line of the summary below, and — only if `OPEN_KNOWN_BUGS` (Phase 1) was non-empty and
+overlapped this card — confirm the `[retest: {BUG-ID}]` test from 3a actually ran and note its
+outcome. This does not block or gate anything — it only makes sure nothing gets buried in the
+summary.
+
+Show the final summary:
 
 ```
 Manual Testing Complete — [CARD_ID]
 
   UI Testing (Figma)  : [completed / skipped]
   Manual Testing      : X Pass | X Fail | X Observation | X Blocked
-  Bug Reporting       : [N] bug(s) filed — [keys]
+  Bug Reporting       : [N] bug(s) filed — [keys] [+ "⚠ High-severity on {dimension}" if applicable]
   Test Charter        : [published URL or "saved locally"]
   Automation hints    : outputs/automation-hints-[CARD_ID]-[YYYYMMDD].md
 ```