@roopesh.yadava/qa-pack 1.0.3 → 1.1.0

package/README.md

@@ -10,7 +10,7 @@ echo "@roopesh.yadava:registry=https://registry.npmjs.org" >> .npmrc
 npm install --save-dev @roopesh.yadava/qa-pack
 ```
 
-On install, the postinstall script copies all skills and commands into `.claude/` and creates one-time config files (`CLAUDE.md`, `.mcp.json`, `cucumber.cjs`) if they don't already exist. It also writes the `.npmrc` scope entry above automatically, so `npm update` works with no extra steps after the first install.
+On install, the postinstall script copies all skills and commands into `.claude/` (git-ignored — see Git hygiene below) and creates one-time config files (`CLAUDE.md`, `.mcp.json`, `cucumber.cjs`, `.env`) if they don't already exist. It also writes the `.npmrc` scope entry above automatically, so `npm update` works with no extra steps after the first install.
 
 ## Update
 
@@ -18,19 +18,16 @@ On install, the postinstall script copies all skills and commands into `.claude/
 npm update @roopesh.yadava/qa-pack
 ```
 
-Skill files are overwritten with the latest version. Your `CLAUDE.md`, `.mcp.json`, and — critically — `product_context/` (your accumulated run history and known bugs) are **never touched**.
+Skill files are overwritten with the latest version. Your `CLAUDE.md`, `.mcp.json`, `.env`, and — critically — `product_context/` (your accumulated run history and known bugs) are **never touched**.
 
 ## First-time setup
 
-After installing, open `CLAUDE.md` at your repo root and fill in:
+After installing:
 
-```
-Jira Project Key:  PROJ
-App URL:           https://your-app.example.com
-Auth Method:       form_login | SSO | token | none
-OTP Required:      yes (always 999999) | no
-Username / Password: your test credentials
-```
+1. Open `.env` (gitignored) and fill in the secrets:
+   `QA_APP_URL`, `QA_LOGIN_URL`, `QA_USERNAME`, `QA_PASSWORD`, `QA_OTP_CODE`
+   (plus `JIRA_BASE_URL` / `JIRA_EMAIL` / `JIRA_API_TOKEN` if you want bug screenshots attached).
+2. Open `CLAUDE.md` and fill in the non-secret project facts (Jira key, environment, auth method).
 
 Then open the repo in Claude Code and run:
 
@@ -38,13 +35,30 @@ Then open the repo in Claude Code and run:
 run qa PROJ-123
 ```
 
+## How the QA agent works
+
+Every run follows the same structured flow:
+
+1. **Card input** — give a Jira card ID (`run qa PROJ-123`)
+2. **Product context** — saved context + the Jira card are loaded automatically
+3. **Gap questions** — you're asked only what isn't already known (one message)
+4. **Phase selection**:
+   - **Phase 1 — Manual testing** (UI/Figma diff → browser tests → bugs → charter)
+   - **Phase 2 — Write automation** (reuse audit → Gherkin → steps → POM → real run + self-heal)
+   - **Phase 3 — Both** (manual first — its findings feed the automation)
+
+Automation is **reuse-first**: existing `.feature` files and step definitions are catalogued
+before any Gherkin is written, drafted steps must match existing ones (exact → parameterized
+→ reworded) before a new step definition is allowed, and each run reports its reuse %.
+
 ## Triggers
 
 | Say this | What happens |
 |---|---|
-| `run qa PROJ-123` | Full QA — manual or automation branch |
-| `manual test PROJ-123` | Playwright manual testing + bug filing |
-| `automate PROJ-123` | Gherkin + step defs + POM |
+| `run qa PROJ-123` | Structured flow — context, questions, then phase menu |
+| `manual test PROJ-123` | Phase 1 — manual testing + bug filing |
+| `automate PROJ-123` | Phase 2 — reuse-first BDD automation |
+| `full QA PROJ-123` | Phase 3 — manual first, then automation |
 | `accessibility test PROJ-123` | WCAG 2.1 A/AA audit |
 | `ui test PROJ-123` | Live app vs Figma design diff |
 | `file a bug` | Files bug directly to Jira |
@@ -58,10 +72,19 @@ run qa PROJ-123
 | `.claude/commands/*.md` | Always overwritten |
 | `.claude/skills/qa-agent/product_context/**` | **Never touched** after first seed |
 | `.claude/settings.json` | Created once, never overwritten |
-| `CLAUDE.md`, `.mcp.json`, `cucumber.cjs` | Created once, never overwritten |
+| `CLAUDE.md`, `.mcp.json`, `cucumber.cjs`, `.env` | Created once, never overwritten |
+| `.env.example` | Always refreshed (shows latest env keys) |
 | `.claude/settings.local.json` | Created once from example |
 | `.claude/settings.local.json.example` | Always refreshed (shows latest options) |
-| `.gitignore` | `outputs/` and `settings.local.json` appended if missing |
+| `.gitignore` | Managed `# >>> qa-pack` block regenerated on every install — ignores all pack-installed skills/commands plus `outputs/`, session files, and local settings |
+
+## Git hygiene
+
+Everything qa-pack copies into `.claude/` is git-ignored via a managed block in your `.gitignore` (between `# >>> qa-pack` and `# <<< qa-pack` markers). Your product repo's **own** skills in `.claude/skills/` are not affected — only the pack's skill folders are listed by name. The block is regenerated on every install, so skills added in future versions are ignored automatically; anything you write outside the markers is never touched.
+
+Secrets live only in `.env` (gitignored). `product_context/` contains no credentials but lives inside an ignored folder, so it also stays out of git — each machine builds its own context from its runs.
+
+If you installed an older qa-pack version and already committed the skill files, postinstall prints the one-time `git rm -r --cached` command to untrack them (files stay on disk).
 
 ## Publishing (maintainers)
 

package/bin/postinstall.js

@@ -71,6 +71,16 @@ const commandsSrc = path.join(PACK_DIR, 'claude', 'commands');
 const commandsDest = path.join(PROJECT_ROOT, '.claude', 'commands');
 copyDir(commandsSrc, commandsDest, () => true);
 
+// ── 2b. Stamp pack version into the copied SKILLS_CONTEXT.md ──────────────────
+const packVersion = require(path.join(PACK_DIR, 'package.json')).version;
+const contextMapDest = path.join(skillsDest, 'SKILLS_CONTEXT.md');
+if (fs.existsSync(contextMapDest)) {
+  const stamped = fs
+    .readFileSync(contextMapDest, 'utf8')
+    .replace('{{QA_PACK_VERSION}}', packVersion);
+  fs.writeFileSync(contextMapDest, stamped);
+}
+
 // ── 3. settings.json — create only if missing ─────────────────────────────────
 copyFile(
   path.join(PACK_DIR, 'claude', 'settings.json'),
@@ -99,7 +109,14 @@ const templates = [
   ['templates/CLAUDE.md',    'CLAUDE.md'],
   ['templates/mcp.json',     '.mcp.json'],
   ['templates/cucumber.cjs', 'cucumber.cjs'],
+  ['templates/.env.example', '.env'],
 ];
+// Always refresh the .env.example reference copy (like settings.local.json.example)
+copyFile(
+  path.join(PACK_DIR, 'templates', '.env.example'),
+  path.join(PROJECT_ROOT, '.env.example'),
+  { overwrite: true }
+);
 for (const [src, dest] of templates) {
   copyFile(
     path.join(PACK_DIR, src),
@@ -122,20 +139,65 @@ if (fs.existsSync(npmrcPath)) {
   log.added.push('.npmrc');
 }
 
-// ── 7. .gitignore — ensure outputs/ and settings.local.json are ignored ───────
-const gitignorePath = path.join(PROJECT_ROOT, '.gitignore');
-const gitignoreEntries = ['outputs/', '.claude/settings.local.json'];
-if (fs.existsSync(gitignorePath)) {
-  let content = fs.readFileSync(gitignorePath, 'utf8');
-  const toAdd = gitignoreEntries.filter(e => !content.includes(e));
-  if (toAdd.length) {
-    content += `\n# qa-pack\n${toAdd.join('\n')}\n`;
-    fs.writeFileSync(gitignorePath, content);
-    log.updated.push('.gitignore');
+// ── 7. .gitignore — managed block covering everything qa-pack installs ────────
+// Regenerated on every install from the pack contents, so newly added skills
+// are ignored automatically. Delimited by markers; user entries outside the
+// block are never touched.
+const GITIGNORE_START = '# >>> qa-pack (managed by @roopesh.yadava/qa-pack — do not edit this block)';
+const GITIGNORE_END = '# <<< qa-pack';
+
+function packIgnoreEntries() {
+  const entries = [
+    'outputs/',
+    '.env',
+    '.playwright-session.json',
+    '.claude/settings.local.json',
+    '.claude/settings.local.json.example',
+  ];
+  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+    entries.push(entry.isDirectory()
+      ? `.claude/skills/${entry.name}/`
+      : `.claude/skills/${entry.name}`);
   }
-} else {
-  fs.writeFileSync(gitignorePath, `# qa-pack\n${gitignoreEntries.join('\n')}\n`);
-  log.added.push('.gitignore');
+  for (const entry of fs.readdirSync(commandsSrc, { withFileTypes: true })) {
+    if (entry.isFile()) entries.push(`.claude/commands/${entry.name}`);
+  }
+  return entries;
+}
+
+const gitignorePath = path.join(PROJECT_ROOT, '.gitignore');
+const ignoreEntries = packIgnoreEntries();
+const managedBlock = `${GITIGNORE_START}\n${ignoreEntries.join('\n')}\n${GITIGNORE_END}\n`;
+
+let gitignoreContent = fs.existsSync(gitignorePath)
+  ? fs.readFileSync(gitignorePath, 'utf8')
+  : '';
+const gitignoreExisted = gitignoreContent !== '' || fs.existsSync(gitignorePath);
+const before = gitignoreContent;
+
+// Drop any previous managed block
+const blockRe = new RegExp(
+  `${GITIGNORE_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${GITIGNORE_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n?`,
+  'g'
+);
+gitignoreContent = gitignoreContent.replace(blockRe, '');
+
+// Drop the legacy "# qa-pack" header and loose duplicates of managed entries
+gitignoreContent = gitignoreContent
+  .split('\n')
+  .filter(line => {
+    const t = line.trim();
+    return t !== '# qa-pack' && !ignoreEntries.includes(t);
+  })
+  .join('\n');
+
+if (gitignoreContent && !gitignoreContent.endsWith('\n')) gitignoreContent += '\n';
+if (gitignoreContent && !gitignoreContent.endsWith('\n\n')) gitignoreContent += '\n';
+gitignoreContent += managedBlock;
+
+if (gitignoreContent !== before) {
+  fs.writeFileSync(gitignorePath, gitignoreContent);
+  (gitignoreExisted ? log.updated : log.added).push('.gitignore');
 }
 
 // ── Summary ───────────────────────────────────────────────────────────────────
@@ -146,6 +208,25 @@ if (log.skipped.length)    console.log('  Skipped  :', log.skipped.join(', '));
 if (log.protected.length)  console.log('  Protected:', log.protected.join(', '), '(product context — never overwritten)');
 
 if (log.added.includes('CLAUDE.md')) {
-  console.log('\n  Next: open CLAUDE.md and fill in your Jira project key, app URL, and credentials.');
+  console.log('\n  Next: fill in secrets in .env (QA_APP_URL, QA_USERNAME, QA_PASSWORD, ...)');
+  console.log('        and project facts in CLAUDE.md (Jira key, environment, auth method).');
 }
+
+// If pack files were committed before this version, .gitignore alone won't hide
+// them — they must be removed from the git index once.
+try {
+  const { execSync } = require('child_process');
+  const packPaths = ignoreEntries.filter(e => e.startsWith('.claude/'));
+  const tracked = execSync(
+    `git ls-files -- ${packPaths.map(p => JSON.stringify(p)).join(' ')}`,
+    { cwd: PROJECT_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+  ).trim();
+  if (tracked) {
+    const trackedRoots = [...new Set(
+      tracked.split('\n').map(f => packPaths.find(p => f === p || f.startsWith(p)))
+    )].filter(Boolean);
+    console.log('\n  Note: qa-pack files are currently tracked by git. To untrack them (keeps files on disk):');
+    console.log(`    git rm -r --cached ${trackedRoots.join(' ')} && git commit -m "chore: untrack qa-pack files"`);
+  }
+} catch (_) { /* not a git repo or git unavailable — nothing to do */ }
 console.log('');

package/claude/commands/qa-agent.md

@@ -1,12 +1,12 @@
 ---
 name: qa-agent
-description: Launch the QA Agent — presents the skill menu and dispatches to the right skill based on your input.
-argument-hint: "[Jira card ID | 'full QA' | skill name | plain description]"
+description: Launch the QA Agent — card → product context → gap questions → phase selection (1 Manual / 2 Automation / 3 Both).
+argument-hint: "[Jira card ID | 'full QA PROJ-123' | skill name | plain description]"
 user-invocable: true
 ---
 
 Invoke the `qa-agent` skill.
 
-If the user provided an argument (e.g. a Jira card ID or the phrase "full QA for PROJ-123"),
-pass it directly into the skill as the initial intent so the agent does not re-ask for input
-it has already received.
+If the user provided an argument (e.g. a Jira card ID, "full QA for PROJ-123", or a phase
+choice), pass it directly into the skill as the initial intent so the agent does not
+re-ask for input it has already received.

package/claude/skills/SKILLS_CONTEXT.md

@@ -1,7 +1,21 @@
 # QA Skills — Context Map
+
+**qa-pack version: {{QA_PACK_VERSION}}**
+
 <!-- Generated by graphify from .claude/skills. Load this instead of individual SKILL.md files
      when you only need pipeline structure. Load a specific SKILL.md only when executing that skill. -->
 
+## Secrets Rule — All Skills Must Follow
+
+App URL, credentials, OTP code, and Jira REST tokens live in `.env` at the repo root
+(`QA_APP_URL`, `QA_LOGIN_URL`, `QA_USERNAME`, `QA_PASSWORD`, `QA_OTP_CODE`,
+`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`).
+
+- Read `.env` ONCE at skill start (Read tool). Precedence: `.env` > product context > ask the user.
+- **Never print `QA_PASSWORD` or `JIRA_API_TOKEN`** to chat, reports, hints files, or product context.
+- Never write credentials into `context.md`, `CLAUDE.md`, or any `outputs/` file.
+- If a required value is missing from `.env`, ask for it once and suggest the user add it to `.env`.
+
 ## Global Token Rules — All Skills Must Follow
 
 These rules apply to every skill, every run. Violating them is the single biggest source of token waste.
@@ -65,26 +79,28 @@ Jira Card ID (Atlassian MCP)
          │
          ▼
   ┌──────────────┐
-  │   qa-agent   │  ← entry point for all paths
+  │   qa-agent   │  ← entry point: card → context → gap questions → phase menu
   └──────┬───────┘
          │
-    ┌────┴────┐
-    ▼         ▼
-[AUTO]      [MANUAL]
-    │            │
-    ▼            ▼ ─────────────────────────────┐
-automation  ui-test-figma (Figma MCP + Playwright CLI)
-    │            │
-    │        manual-testing (Playwright MCP)
-    │            │
-    │        bug-reporting (Atlassian MCP)
-    │            │
-    │        test-charter (REST API publish)
-    │            │
-    └────────────┘
+   ┌─────┼──────────────┐
+   ▼     ▼              ▼
+[PHASE 1]  [PHASE 2]  [PHASE 3 = Phase 1 THEN Phase 2]
+ MANUAL     AUTOMATION   (manual first — its automation-hints
+   │            │         file feeds Phase 2's selectors)
+   ▼            ▼
+ui-test-figma  reuse audit (step catalog + repo layout discovery)
+   │            │
+manual-testing Gherkin → Step Defs → POM
+   │            │
+bug-reporting  dry run → REAL RUN → self-heal (≤3)
+   │            │
+test-charter   │
+   └─────┬──────┘
+         │
+    Regression suggestion (Covered Flows overlap)
          │
     Save Product Context
-    (product_context/{PRODUCT}/context.md)
+    (product_context/{PRODUCT}/context.md — no secrets)
          │
     End-to-End Testing complete
 ```
@@ -94,7 +110,7 @@ automation  ui-test-figma (Figma MCP + Playwright CLI)
 | Skill | Input | Output | MCP Needed |
 |-------|-------|--------|------------|
 | `qa-agent` | Jira card ID or menu choice | Dispatches to correct skill | Atlassian |
-| `automation` | Jira card ID | Gherkin + Step Defs + POM + dry-run | Atlassian, Playwright |
+| `automation` | Jira card ID | Reuse audit + Gherkin + Step Defs + POM + real run (reuse % reported) | Atlassian, Playwright |
 | `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 |
@@ -105,22 +121,26 @@ automation  ui-test-figma (Figma MCP + Playwright CLI)
 
 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 Full E2E Pipeline)
+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)
 
 ## Dispatch Map (qa-agent routes)
 
 ```
-"automate CARD"      → automation
-"manual test"        → manual-testing  (calls ui-test-figma → bug-reporting → test-charter internally)
-"ui test"            → ui-test-figma   (standalone)
-"accessibility test" → accessibility-testing (standalone, URL + optional Jira card)
-"file bug"           → bug-reporting   (standalone)
-"charter"            → test-charter    (standalone)
-"full QA"            → automation THEN manual-testing → End-to-End complete
+Phase 1 / "manual test"    → manual-testing  (calls ui-test-figma → bug-reporting → test-charter internally)
+Phase 2 / "automate CARD"  → automation      (reuse audit → Gherkin → steps → POM → run + self-heal)
+Phase 3 / "full QA"        → manual-testing THEN automation (hints file reused) → End-to-End complete
+"ui test"                  → ui-test-figma   (standalone)
+"accessibility test"       → accessibility-testing (standalone, URL + optional Jira card)
+"file bug"                 → bug-reporting   (standalone)
+"charter"                  → test-charter    (standalone)
 ```
 
+**Input collection happens ONCE in qa-agent.** Sub-skills receive their parameters in the
+invocation message (card ID, URLs, flags) and read secrets from `.env` — they must not
+re-ask for anything qa-agent already passed.
+
 ## Playwright Usage Guide (token budget)
 
 ### Expensive (avoid unless needed)
@@ -140,17 +160,28 @@ browser_evaluate("() => JSON.stringify({ls: {...localStorage}, ss: {...sessionSt
 # Later CLI screenshots use: --storage-state .playwright-session.json
 ```
 
-## Token Tracking — canonical pattern (all skills follow this)
+## Token Tracking — OPTIONAL, canonical pattern (all skills follow this)
+
+Token tracking is **disabled by default** and must never break a run.
+
+**Enablement check — run ONCE at skill start, silently:**
+```bash
+[ -n "$QA_TRACKING_DIR" ] && [ -f "$QA_TRACKING_DIR/track_tokens.py" ] \
+  && echo TRACKING_ENABLED || echo TRACKING_DISABLED
+```
+(`QA_TRACKING_DIR` comes from `.env`. If the variable is unset, the scripts are missing,
+or any tracking command errors — **skip ALL tracking commands for the rest of the run
+silently**. Never mention tracking to the user, never retry a failed tracking call.)
 
-**Rules:** Silent background task. Never mention in conversation. Replace `CARD_ID` with the actual card ID.
-Scripts live at `/home/user/projects/Smart-testing-with-AI-Agents/`.
+**When enabled** — silent background task. Replace `CARD_ID` with the actual card ID:
 
 ```bash
-PROJECT=/home/user/projects/Smart-testing-with-AI-Agents
+PROJECT=$QA_TRACKING_DIR
+MODEL=${QA_TRACKING_MODEL:-claude}
 
 # Entry (before any work)
 SNAP=$(python3 $PROJECT/context_snapshot.py --phase start) && \
-python3 $PROJECT/track_tokens.py start --card CARD_ID $SNAP --model claude-sonnet-4-6
+python3 $PROJECT/track_tokens.py start --card CARD_ID $SNAP --model $MODEL
 
 # After each phase (repeat per checkpoint, replacing PHASE_NAME)
 SNAP=$(python3 $PROJECT/context_snapshot.py --phase PHASE_NAME) && \
@@ -158,13 +189,13 @@ python3 $PROJECT/track_tokens.py phase --card CARD_ID --name PHASE_NAME $SNAP
 
 # Exit (after skill completes)
 SNAP=$(python3 $PROJECT/context_snapshot.py --phase end) && \
-python3 $PROJECT/track_tokens.py end --card CARD_ID $SNAP --model claude-sonnet-4-6 && \
+python3 $PROJECT/track_tokens.py end --card CARD_ID $SNAP --model $MODEL && \
 python3 $PROJECT/track_tokens.py report && \
 python3 $PROJECT/track_tokens.py session
 ```
 
 **Phase names by skill:**
-- automation: `start` → `jira_fetch` → `gherkin_generation` → `step_definitions` → `pom_generation` → `end`
+- 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`
@@ -189,6 +220,9 @@ First run will always be 0% (cold cache). Second and subsequent runs should cach
 | Accessibility report | `outputs/a11y-report-[slug]-[date].md` |
 | Accessibility baseline screenshot | `outputs/screenshots/a11y-baseline-[slug].png` |
 | 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` |
+| 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` |

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

@@ -4,7 +4,7 @@ description: >
   Tests a live web page against WCAG 2.1 Level A and AA criteria. Injects axe-core via
   browser_evaluate for automated rule checks, then runs manual keyboard, focus, skip-link,
   heading, and alt-text checks via Playwright MCP. Accepts a full page URL, logs in with
-  Playwright MCP (OTP always 999999), navigates to the target page, runs all checks, saves
+  Playwright MCP (credentials/OTP from .env), navigates to the target page, runs all checks, saves
   a structured report to outputs/, and files violations as Jira bugs on the provided card.
   Uses Playwright CLI for zero-token screenshots. Token tracking enabled.
   Standalone or callable from qa-agent.
@@ -13,7 +13,7 @@ description: >
   or "check accessibility".
 compatibility: >
   Playwright MCP must be running. axe-core injected at runtime from CDN — no install needed.
-  OTP always 999999. Playwright CLI (npx playwright) must be available.
+  OTP code from .env QA_OTP_CODE. Playwright CLI (npx playwright) must be available.
 user-invocable: true
 ---
 
@@ -30,7 +30,8 @@ user-invocable: true
 
 ## Token Tracking
 
-Silent background task — follow the **Token Tracking** pattern in `SKILLS_CONTEXT.md`.
+Optional and silent — follow the **Token Tracking** pattern in `SKILLS_CONTEXT.md`
+(run its enablement check once at skill start; if disabled, skip every checkpoint silently).
 Checkpoints: `start` → `login` → `a11y_checks` → `end + report + session`.
 Use `CARD_ID` if Jira card provided, else `"a11y-test"`. Never show tracking output to user.
 
@@ -87,11 +88,10 @@ Check the current URL:
 - Redirected to `/login`, `/sign-in`, `/auth` → session not active, ask for credentials.
 - Dashboard / main nav visible → session already active, skip to Step 2.
 
-If login needed:
-> "What is the **email** for login?"
-> (after answer) "And the **password**?"
+If login needed: read `.env` for `QA_USERNAME` / `QA_PASSWORD` / `QA_OTP_CODE` first.
+Only if still missing, ask for email + password in one message (never print the password).
 
-Store: `EMAIL`, `PASSWORD`.
+Store: `EMAIL`, `PASSWORD`, `OTP_CODE`.
 
 Once all inputs collected:
 > "Got it — logging in and starting the accessibility checks..."
@@ -111,7 +111,7 @@ Once all inputs collected:
 
 **If OTP screen appears** (6-digit input / PIN boxes):
 7. `browser_click` first OTP input box
-8. `browser_type(text: "999999")` — always this value, auto-advances through boxes
+8. `browser_type(text: OTP_CODE)` — the `QA_OTP_CODE` value from `.env`, auto-advances through boxes
 9. `browser_click` Verify / Confirm button
 10. `browser_wait_for(state: "networkidle")`
 
@@ -313,5 +313,5 @@ Accessibility Testing Complete
 | `browser_evaluate` returns null | Log "script returned null" for that check, continue |
 | Jira card not found | Ask to verify key; offer to save report only |
 | Jira bug creation fails | Note failure, continue remaining bugs, report failures at end |
-| OTP screen appears unexpectedly | Type `"999999"`, proceed |
+| OTP screen appears unexpectedly | Type the `QA_OTP_CODE` value from `.env`, proceed |
 | Page requires further navigation after login | Follow redirect, confirm TARGET_URL loads |

package/claude/skills/automation/LOCATOR_PATTERNS.md

@@ -113,7 +113,7 @@ first box only populates one digit and the component does not auto-advance.
 
 ```javascript
 // ❌ WRONG — only fills box 1, leaves 5 empty
-await this.otpInput.fill('999999');
+await this.otpInput.fill(process.env.QA_OTP_CODE);
 
 // ✅ CORRECT — click first box to focus, then type digit-by-digit
 await this.otpInput.waitFor({ state: 'visible', timeout: 15000 });