@roopesh.yadava/qa-pack 1.4.0 → 1.5.0

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

@@ -70,6 +70,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, roam-testing | DOM fingerprint cache — `UNCHANGED` means skip re-discovery |
+| `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 | automation (record), qa-agent (status) | Trust ratchet on Gate 1/Gate 2 approvals |
+| `locator-record` / `locator-query` --product P --page U | automation | Self-improving locator memory across self-heal fixes |
+| `dashboard` / `digest [--days N]` / `roi` | qa-insights | Cross-product reports — 100% script-generated, zero synthesis |
+
+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,6 +144,10 @@ 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.
+
 ## Skills — One-Line Summary
 
 | Skill | Input | Output | MCP Needed |
@@ -116,14 +159,17 @@ test-charter   │
 | `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 +181,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
@@ -236,3 +284,11 @@ First run will always be 0% (cold cache). Second and subsequent runs should cach
 | 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` |

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

@@ -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.