@roopesh.yadava/qa-pack 1.3.0 → 1.5.0

package/claude/skills/k6-framework-scaffold/scaffold.sh

@@ -0,0 +1,388 @@
+#!/usr/bin/env bash
+# k6-framework-scaffold — create a ready-to-use k6 load-testing framework in the CURRENT repo.
+# Usage:  bash .claude/skills/k6-framework-scaffold/scaffold.sh [--force]
+#   (no flag) aborts if k6-performance-tests/ already exists.
+#   --force   scaffolds into an existing folder; still never overwrites an existing file.
+set -euo pipefail
+
+ROOT="k6-performance-tests"
+FORCE="${1:-}"
+
+if [ -d "$ROOT" ] && [ "$FORCE" != "--force" ]; then
+  echo "ERROR: $ROOT/ already exists. Re-run with --force to add only missing files." >&2
+  exit 1
+fi
+
+# w <relative-path> : write heredoc (stdin) to $ROOT/<path>, only if the file doesn't exist.
+w() {
+  local path="$1"
+  if [ -f "$ROOT/$path" ]; then echo "  skip (exists): $path"; cat >/dev/null; return; fi
+  mkdir -p "$ROOT/$(dirname "$path")"
+  cat > "$ROOT/$path"
+  echo "  created: $path"
+}
+
+echo "Scaffolding $ROOT/ ..."
+
+# ---------------------------------------------------------------- config/
+w config/env.js <<'EOF'
+// config/env.js — shared configuration. Fill these in for your app + environment.
+
+export const BASE = 'https://api.example.com/v1'; // TODO: API base URL
+export const UI_BASE = 'https://app.example.com'; // TODO: web-app URL (browser tests only)
+
+export const PROJECT_ID = 0; // TODO: Grafana Cloud project id
+
+// Target concurrency — the production peak you reproduce. Rescale by editing these numbers.
+export const CONCURRENT = { userTypeA: 100, userTypeB: 100 };
+export const TOTAL = {
+  userTypeAVUs: CONCURRENT.userTypeA,
+  userTypeBVUs: CONCURRENT.userTypeB,
+  totalVUs: CONCURRENT.userTypeA + CONCURRENT.userTypeB,
+};
+
+// Credentials + ids used by auth and parameterised endpoints.
+export const CREDS = { username: 'TODO', password: 'TODO', otp: '000000' };
+export const TEST_DATA = { sampleId: 'TODO' };
+
+// Include mutating (write) endpoints in the mix? They modify real data on the target env.
+export const ENABLE_WRITES = false;
+
+// Long-lived auth token(s) live in secrets.js (rotate per run).
+export { ACCESS_TOKEN } from './secrets.js';
+EOF
+
+w config/secrets.js <<'EOF'
+// config/secrets.js — auth material, refreshed before each run.
+// ⚠️ Keep production tokens OUT of version control. Use short-lived non-prod tokens.
+export const ACCESS_TOKEN = 'Bearer TODO';
+EOF
+
+w config/profiles.js <<'EOF'
+// config/profiles.js — reusable LOAD PROFILES (the "how much"). A test wires a flow to one.
+
+export function loadProfile({ exec, target, rampUp = '2m', hold = '15m', rampDown = '2m', startVUs = 0 }) {
+  return { executor: 'ramping-vus', exec, startVUs, stages: [
+    { duration: rampUp, target }, { duration: hold, target }, { duration: rampDown, target: 0 },
+  ] };
+}
+export function arrivalRateProfile({ exec, rate, timeUnit = '1m', duration = '15m', preAllocatedVUs = 50, maxVUs = 100 }) {
+  return { executor: 'constant-arrival-rate', exec, rate, timeUnit, duration, preAllocatedVUs, maxVUs };
+}
+export function spikeProfile({ exec, target, rampUp = '30s', hold = '1m', rampDown = '30s', startVUs = 0 }) {
+  return { executor: 'ramping-vus', exec, startVUs, stages: [
+    { duration: rampUp, target }, { duration: hold, target }, { duration: rampDown, target: 0 },
+  ] };
+}
+export function breakpointProfile({ exec, maxRate, ramp = '30m', timeUnit = '1m', preAllocatedVUs = 50, maxVUs = 200 }) {
+  return { executor: 'ramping-arrival-rate', exec, startRate: 0, timeUnit, preAllocatedVUs, maxVUs,
+    stages: [{ duration: ramp, target: maxRate }] };
+}
+export function smokeProfile({ exec, vus = 1, iterations = 1 }) {
+  return { executor: 'per-vu-iterations', exec, vus, iterations, maxDuration: '1m' };
+}
+export function enduranceProfile({ exec, target, rampUp = '2m', hold = '2h', rampDown = '2m', startVUs = 0 }) {
+  return { executor: 'ramping-vus', exec, startVUs, stages: [
+    { duration: rampUp, target }, { duration: hold, target }, { duration: rampDown, target: 0 },
+  ] };
+}
+EOF
+
+# ---------------------------------------------------------------- lib/
+w lib/http.js <<'EOF'
+// lib/http.js — shared request headers + response handling.
+import { check } from 'k6';
+
+// `token` is the full Bearer string. Each flow passes its own token.
+export function authHeaders(token, extra = {}) {
+  return { Authorization: token, 'Content-Type': 'application/json', ...extra };
+}
+
+// 2xx check; logs 4xx (client-side) with a short body snippet. 5xx tracked by error-rate metric.
+export function checkResponse(res, name) {
+  check(res, { [`${name} ok`]: (r) => r.status >= 200 && r.status < 300 });
+  if (res.status >= 400 && res.status < 500) {
+    const body = String(res.body || '').replace(/\s+/g, ' ').slice(0, 300);
+    console.error(`FAIL ${name} | ${res.status} ${res.request.method} ${res.request.url} | ${body}`);
+  }
+  return res;
+}
+EOF
+
+w lib/rand.js <<'EOF'
+// lib/rand.js — deterministic pseudo-random for load distribution (NOT cryptographic; and
+// intentionally not the JS built-in RNG, which trips security scans). Reproducible runs.
+
+// xorshift32 -> fraction in [0,1). seed = any integer (e.g. the iteration index).
+export function frac(seed) {
+  let x = (seed >>> 0) || 1;
+  x ^= x << 13; x >>>= 0; x ^= x >>> 17; x ^= x << 5; x >>>= 0;
+  return (x >>> 0) / 4294967296;
+}
+
+// Pick a weighted action given the total weight and a value u in [0,1).
+export function weightedPick(actions, totalWeight, u) {
+  const target = u * totalWeight; let acc = 0;
+  for (let i = 0; i < actions.length; i++) { acc += actions[i].weight; if (target <= acc) return actions[i]; }
+  return actions[actions.length - 1];
+}
+EOF
+
+w lib/browser.js <<'EOF'
+// lib/browser.js — checkpoints for browser/ (real-Chromium) tests.
+import { check } from 'k6';
+
+// Element visible within timeout ms (a "stuck UI" surfaces here as a timeout -> failure).
+export async function expectVisible(page, selector, name, timeout = 10000) {
+  let ok = false;
+  try { await page.locator(selector).waitFor({ state: 'visible', timeout }); ok = true; } catch (e) { ok = false; }
+  check(ok, { [`${name} visible`]: (v) => v === true });
+  return ok;
+}
+// Element gone within timeout ms (e.g. a spinner cleared).
+export async function expectHidden(page, selector, name, timeout = 15000) {
+  let ok = false;
+  try { await page.locator(selector).waitFor({ state: 'hidden', timeout }); ok = true; } catch (e) { ok = false; }
+  check(ok, { [`${name} settled`]: (v) => v === true });
+  return ok;
+}
+// Best-effort screenshot (never fails the iteration).
+export async function shot(page, path) { try { await page.screenshot({ path }); } catch (e) {} }
+EOF
+
+# ---------------------------------------------------------------- protocol/api/
+w protocol/api/exampleUser/auth.js <<'EOF'
+// protocol/api/exampleUser/auth.js — token-issuing login. Adapt to your auth, or delete if
+// you only use a pre-issued static token (config/secrets.js).
+import http from 'k6/http';
+import { BASE, CREDS } from '../../../config/env.js';
+import { checkResponse } from '../../../lib/http.js';
+
+const JSON_HEADERS = { 'Content-Type': 'application/json' };
+
+// Example: POST /auth/sign-in -> returns a session (for a two-step OTP flow) or a token.
+export function signIn(tags) {
+  const res = http.post(`${BASE}/auth/sign-in`,
+    JSON.stringify({ username: CREDS.username, password: CREDS.password }),
+    { headers: JSON_HEADERS, tags: { name: 'auth-sign-in', ...tags } });
+  checkResponse(res, 'auth-sign-in');
+  try { return res.json('data.session'); } catch (e) { return null; }
+}
+// If login is two-step (OTP): read the session from signIn() and feed it into a verify() here.
+EOF
+
+w protocol/api/exampleUser/sample.js <<'EOF'
+// protocol/api/exampleUser/sample.js — ENDPOINTS: one function per API call. Copy this shape
+// for each endpoint (add a unique `name` tag so it shows per-endpoint in Grafana).
+import http from 'k6/http';
+import { BASE, TEST_DATA } from '../../../config/env.js';
+import { authHeaders, checkResponse } from '../../../lib/http.js';
+
+export function list(token, tags) {
+  const res = http.get(`${BASE}/sample/list?page=1&limit=10`,
+    { headers: authHeaders(token), tags: { name: 'sample-list', ...tags } });
+  return checkResponse(res, 'sample-list');
+}
+
+export function get(token, tags) {
+  const res = http.get(`${BASE}/sample/get/${TEST_DATA.sampleId}`,
+    { headers: authHeaders(token), tags: { name: 'sample-get', ...tags } });
+  return checkResponse(res, 'sample-get');
+}
+
+// ⚠️ WRITE example — mark write:true in the flow so ENABLE_WRITES can gate it.
+// export function create(token, tags) {
+//   const res = http.post(`${BASE}/sample`, JSON.stringify({ /* ... */ }),
+//     { headers: authHeaders(token), tags: { name: 'sample-create', ...tags } });
+//   return checkResponse(res, 'sample-create');
+// }
+EOF
+
+# ---------------------------------------------------------------- protocol/flows/
+w protocol/flows/exampleUserFlow.js <<'EOF'
+// protocol/flows/exampleUserFlow.js — JOURNEY: a weighted API traffic-split for one user
+// population. Each iteration a VU performs ONE weighted action; over the run the request mix
+// converges to these proportions (= the client's feature-usage %).
+import { sleep } from 'k6';
+import exec from 'k6/execution';
+import { ACCESS_TOKEN, ENABLE_WRITES } from '../../config/env.js';
+import { frac, weightedPick } from '../../lib/rand.js';
+import * as sample from '../api/exampleUser/sample.js';
+
+// Pass/fail thresholds (from the client's SLA).
+export const THRESHOLDS = {
+  http_req_duration: ['p(95)<2000'], // TODO: SLA
+  http_req_failed: ['rate<0.01'],
+};
+
+// weight = share of total traffic (sum ~ 1.0). write:true = mutating (gated by ENABLE_WRITES).
+const ACTIONS = [
+  { weight: 0.7, run: (t) => sample.list(t) },
+  { weight: 0.3, run: (t) => sample.get(t) },
+  // { weight: 0.1, write: true, run: (t) => sample.create(t) },
+];
+const ACTIVE = ENABLE_WRITES ? ACTIONS : ACTIONS.filter((a) => !a.write);
+const TOTAL_WEIGHT = ACTIVE.reduce((s, a) => s + a.weight, 0);
+
+export function exampleUserFlow() {
+  const token = ACCESS_TOKEN;
+  const seed = exec.scenario.iterationInTest + 1;
+  weightedPick(ACTIVE, TOTAL_WEIGHT, frac(seed)).run(token);
+  sleep(1 + frac(seed ^ 0x5bd1e995) * 2); // think time 1-3s
+}
+EOF
+
+# ---------------------------------------------------------------- protocol/tests/
+w protocol/tests/smoke/example.smoke.js <<'EOF'
+// protocol/tests/smoke/example.smoke.js — quick "does it work?" before a big run.
+import { PROJECT_ID } from '../../../config/env.js';
+import { smokeProfile } from '../../../config/profiles.js';
+import { THRESHOLDS } from '../../flows/exampleUserFlow.js';
+export { exampleUserFlow } from '../../flows/exampleUserFlow.js';
+
+export const options = {
+  cloud: { projectID: PROJECT_ID, name: 'MyApp API — Smoke' },
+  scenarios: { smoke: smokeProfile({ exec: 'exampleUserFlow', vus: 1, iterations: 1 }) },
+  thresholds: THRESHOLDS,
+};
+EOF
+
+w protocol/tests/load/example.load.js <<'EOF'
+// protocol/tests/load/example.load.js — the expected-peak run.
+import { PROJECT_ID, TOTAL } from '../../../config/env.js';
+import { loadProfile } from '../../../config/profiles.js';
+import { THRESHOLDS } from '../../flows/exampleUserFlow.js';
+export { exampleUserFlow } from '../../flows/exampleUserFlow.js';
+
+export const options = {
+  cloud: { projectID: PROJECT_ID, name: 'MyApp API — Load' },
+  scenarios: {
+    users: loadProfile({ exec: 'exampleUserFlow', target: TOTAL.userTypeAVUs, hold: '15m' }),
+  },
+  thresholds: THRESHOLDS,
+};
+EOF
+
+w protocol/tests/spike/README.md <<'EOF'
+# Spike tests
+Copy a load test here and swap the profile to `spikeProfile` (config/profiles.js) — a sudden
+burst then a quick drop, to check the system survives/recovers from a surge.
+EOF
+
+w protocol/tests/breakpoint/README.md <<'EOF'
+# Breakpoint tests
+Ramp load upward until it breaks (find capacity). Use `breakpointProfile` and pair with an
+`abortOnFail` threshold so the run stops at the breaking point.
+EOF
+
+w protocol/tests/endurance/README.md <<'EOF'
+# Endurance (soak) tests
+Moderate, sustained load for hours (memory leaks, resource growth). Use `enduranceProfile`.
+EOF
+
+# ---------------------------------------------------------------- browser/ (OPTIONAL)
+w browser/pages/exampleApp/loginPage.js <<'EOF'
+// browser/pages/exampleApp/loginPage.js — PAGE OBJECT (selectors + actions). Fill selectors
+// from the real DOM/source. SPA-safe: wait on the next screen's element, not full navigation.
+import { UI_BASE, CREDS } from '../../../config/env.js';
+
+const SEL = {
+  username: '#username',       // TODO
+  password: '#password',       // TODO
+  submit: '[data-testid="submit"]', // TODO
+};
+
+export async function login(page) {
+  await page.goto(`${UI_BASE}/login`, { waitUntil: 'networkidle' });
+  await page.locator(SEL.username).fill(CREDS.username);
+  await page.locator(SEL.password).fill(CREDS.password);
+  await page.locator(SEL.submit).click();
+}
+EOF
+
+w browser/pages/exampleApp/samplePage.js <<'EOF'
+// browser/pages/exampleApp/samplePage.js — checkpoints for a screen.
+import { expectVisible } from '../../../lib/browser.js';
+const SEL = { root: '[data-testid="page-root"]' }; // TODO
+export async function assertLoaded(page) {
+  return expectVisible(page, SEL.root, 'sample-page', 15000);
+}
+EOF
+
+w browser/flows/exampleUiFlow.js <<'EOF'
+// browser/flows/exampleUiFlow.js — UI JOURNEY (real browser): login -> a screen renders.
+import { browser } from 'k6/browser';
+import * as loginPage from '../pages/exampleApp/loginPage.js';
+import * as samplePage from '../pages/exampleApp/samplePage.js';
+import { shot } from '../../lib/browser.js';
+
+export const UI_THRESHOLDS = {
+  checks: ['rate>0.95'],
+  browser_web_vital_lcp: ['p(90)<2500'], // TODO: tune to UX SLA
+};
+
+export async function exampleUiJourney() {
+  const page = await browser.newPage();
+  try {
+    await loginPage.login(page);
+    const ok = await samplePage.assertLoaded(page);
+    await shot(page, `screenshots/example-${ok ? 'ok' : 'FAIL'}.png`);
+  } finally {
+    await page.close();
+  }
+}
+EOF
+
+w browser/tests/exampleUi.browser.js <<'EOF'
+// browser/tests/exampleUi.browser.js — run a FEW real-browser VUs (each is a real Chromium,
+// so keep counts small). Headless by default; K6_BROWSER_HEADLESS=false to watch locally.
+import { PROJECT_ID } from '../../config/env.js';
+import { UI_THRESHOLDS } from '../flows/exampleUiFlow.js';
+export { exampleUiJourney } from '../flows/exampleUiFlow.js';
+
+export const options = {
+  cloud: { projectID: PROJECT_ID, name: 'MyApp UI — Example Journey (browser)' },
+  scenarios: {
+    ui: {
+      executor: 'per-vu-iterations', exec: 'exampleUiJourney', vus: 1, iterations: 1,
+      maxDuration: '3m', options: { browser: { type: 'chromium' } },
+    },
+  },
+  thresholds: UI_THRESHOLDS,
+};
+EOF
+
+# ---------------------------------------------------------------- root files
+w .gitignore <<'EOF'
+config/secrets.local.js
+.env
+*.k6-summary.json
+summary.json
+screenshots/
+EOF
+
+w README.md <<'EOF'
+# k6 Performance & UX Test Framework
+
+Two layers, sharing `config/` + `lib/`:
+- **protocol/** — API / HTTP load (the CORE, every app). api/ (endpoints) -> flows/ (weighted
+  traffic-split + thresholds) -> tests/ (wire a flow to a load profile).
+- **browser/** — real-browser UX (OPTIONAL; UI-heavy apps only). Delete this folder if unneeded.
+
+## Fill in
+1. `config/env.js` — BASE / UI_BASE / PROJECT_ID / scale numbers / test data.
+2. `config/secrets.js` — auth token(s) (keep out of VCS).
+3. `protocol/api/**` — one function per real endpoint.
+4. `protocol/flows/**` — weighted action table (feature-usage %) + thresholds (SLA).
+
+## Run (from inside this folder)
+```
+k6 cloud login --token <GRAFANA_CLOUD_TOKEN>
+k6 run       protocol/tests/smoke/example.smoke.js    # local sanity
+k6 cloud run protocol/tests/load/example.load.js       # on Grafana Cloud
+# browser (optional): k6 run browser/tests/exampleUi.browser.js
+```
+EOF
+
+echo "Done. Structure created under $ROOT/"
+echo "Next: fill config/env.js + config/secrets.js, then replace the example endpoints/flows."

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

@@ -95,6 +95,10 @@ 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.
+
 Run token tracking `jira_fetch` checkpoint.
 
 ### 1b — Truncate Jira data if card is verbose
@@ -170,7 +174,18 @@ From the AC, generate numbered test ideas:
 - 2+ negative/edge case tests
 - 1+ error state test
 
-Show as a compact table (T-01, T-02 ... with name and expected outcome).
+**Risk-based 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"
+```
+
+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 AC order in that case, no need to mention it.
+
+Show as a compact table (T-01, T-02 ... with name and expected outcome), risk-ordered.
 Ask: `"Ready to run these tests? (yes / no or edit)"` — include any missing navigation
 questions in this same message.
 Proceed on confirmation.
@@ -241,6 +256,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):
@@ -346,7 +376,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
@@ -386,6 +416,41 @@ Derive all fields from test execution data — no user input needed:
 | Severity | AC explicitly failed → High · Assertion failed → Medium · Observation → Low |
 | 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:

package/claude/skills/qa-agent/SKILL.md

@@ -76,6 +76,8 @@ If the user's message contains `--reset-context`:
 Extract the project key prefix from the card ID (`QE-89` → `QE`). Check
 `.claude/skills/qa-agent/product_context/{PREFIX}/context.md`; if not found by exact
 prefix, check whether any folder under `product_context/` starts with that prefix.
+Whichever folder name matches, store it as `PRODUCT_FOLDER` for the rest of this run (Steps
+1d and 3 below use it) — it will be re-derived/confirmed from the Jira project name in Step 6a.
 
 **If found:** read it once and store `CTX_APP_URL`, `CTX_LOGIN_URL`, `CTX_OTP`,
 `CTX_ENVIRONMENT`, plus the Covered Flows and Known Bugs tables (needed for Steps 2 and 5).
@@ -112,6 +114,17 @@ only — qa-pack has no way to force a mid-run model switch, so proceed on whate
 active regardless of the user's choice. See `SKILLS_CONTEXT.md` → "Model Routing" for the
 opt-in subagent-override pattern some environments can wire up instead.
 
+### 1d — Pre-run Cost Estimate
+
+**Only if Step 1a found an existing product folder.** This is a plain script call, not a
+reasoning step — run it and print its one line verbatim, prefixed `"Cost estimate: "`:
+
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs cost-estimate --product {PRODUCT_FOLDER}
+```
+
+Skip entirely on a product's first run (no context file yet — nothing to estimate from).
+
 ---
 
 ## Step 2 — Ask Relevant Questions (gaps only)
@@ -176,6 +189,23 @@ Set `AUTO_APPROVE = true` only when ALL hold:
 Set `AUTO_APPROVE = false` otherwise, or when the user said "manual gates" / "confirm each
 step" / "don't auto-approve", or when `--reset-context` was passed.
 
+### Trust Ratchet (only when AUTO_APPROVE would otherwise be false, and a product folder exists)
+
+One script call, before showing the phase table:
+
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs trust-status --product {PRODUCT_FOLDER}
+```
+
+- Prints `ELIGIBLE`: add one line to the phase-selection message — "This product has a clean
+  approval streak — reply **auto** to skip manual gates for this run." If the user replies
+  `auto`, set `AUTO_APPROVE = true` for this run only (does not change future runs or other
+  products).
+- Prints `NOT_ELIGIBLE`: say nothing — do not mention trust status at all.
+
+The streak itself is recorded by the `automation` skill at each gate (see its SKILL.md) —
+qa-agent only reads the status here.
+
 ---
 
 ## Step 4 — Pre-flight Check + Dispatch

package/claude/skills/qa-agent/product_context/README.md

@@ -17,3 +17,19 @@ The QA Agent writes to `{PRODUCT}/context.md` automatically at the end of every
 - Known bugs accumulated across all runs
 - Covered test flows
 - Environment notes (URLs, quirks — never credentials; those live only in `.env`)
+
+## Other files that may appear in a product folder
+
+These are written and read exclusively by `.claude/skills/qa-agent/toolkit/qa-toolkit.cjs`
+— never edited by hand, never read in full by a skill (only queried through the toolkit).
+They exist so features like duplicate-bug detection, DOM-change skipping, and locator
+learning don't have to re-derive their state from `context.md` every run.
+
+| File | Written by | Purpose |
+|------|-----------|---------|
+| `dom-fingerprints.json` | `fingerprint` command | One hash per page URL — lets a run skip DOM re-discovery when nothing changed |
+| `trust.json` | `trust-record` command | Gate 1 / Gate 2 clean-approval streaks — feeds the auto-approve trust ratchet |
+| `locator-learnings.md` | `locator-record` command | Locators that broke before, and what fixed them — read before writing new POM code |
+
+All three are covered by the same `.claude/skills/qa-agent/` gitignore entry as
+`context.md` — they never leave the machine that generated them.