@ia-qa/pal 0.9.0 → 1.0.0

package/skills/ia-qa-pal/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: ia-qa-pal
+description: >-
+  Run one command that walks a web app, maps every page, checks it, compares it with the last
+  tour and reports what broke, what needs a person and what it could not see. Use when asked
+  to watch an app for regressions, to set up QA on a project that has none, to run a QA round
+  or tour, or to find out what a test suite never visits. Requires @ia-qa/pal (`ia-qa-pal`).
+  Runs entirely on the user's machine; no LLM is ever called.
+---
+
+# ia-qa-pal — one tour, one report, no engine of its own
+
+## 1. What it is, and what it is not
+
+pal **composes** `@ia-qa/self-healing`: every verdict it prints comes from that package's own
+functions. It adds no scoring, no heuristic and no second opinion. If a number here disagrees
+with `ia-qa-heal`, that is a bug, not a nuance.
+
+A tour is minutes, not seconds — it drives a real browser over every configured page. Always
+start it in the background and follow it, or you block your own session:
+
+```bash
+npx -p @ia-qa/pal ia-qa-pal tour --background
+npx -p @ia-qa/pal ia-qa-pal status
+```
+
+Through MCP: `pal_project`, `pal_setup`, `pal_tour` (always background), `pal_status`.
+
+## 2. The order, and it is not negotiable
+
+| Step | Command | Why it must come first |
+|---|---|---|
+| 1 | `ia-qa-pal project` | is this project set up at all, and is a tour already running? **Call this first.** |
+| 2 | `ia-qa-pal setup …` | writes `.ia-qa/config.json`. Never overwrites one. |
+| 3 | `ia-qa-pal tour --background` | first tour = **baseline**. It is never a pass. |
+| 4 | `ia-qa-pal status` | follow it; the report lands here |
+| 5 | later tours | the same command. Now it compares. |
+
+`tour` in an unset project returns a typed `setupRequired` with exit 2 rather than guessing an
+answer. That is your cue to run step 2 — after asking the human, never before.
+
+## 3. Setting a project up — ask, never assume
+
+`setup` needs three answers, and **all three are the human's**:
+
+1. **Where the app lives** — the URL you would type in a browser.
+2. **How it logs in** — one of:
+   - `none` — public pages only
+   - `browser` — a person logs in by hand. Hand them `npx -p @ia-qa/self-healing ia-qa-heal login`; **you cannot run it** (§5.1)
+   - `session` — their suite already writes a Playwright `storageState`; ask for its path
+3. **Where their end-to-end tests are** — only if they have some. Skip it rather than guess.
+
+```bash
+npx -p @ia-qa/pal ia-qa-pal setup --url <their app> --login <their answer> --yes
+# add --tests <folder> when they have a suite
+```
+
+It reads the pages from the app's sitemap, falling back to a same-origin crawl (≤ 50 pages).
+Never type a URL, a credential or a test folder the human did not give you. **No setup field
+ever takes a secret**: a login is a `storageState` path or a variable name, never a value.
+
+## 4. Reading the report
+
+Four sections, each appearing only when it holds something — plus one above them all.
+
+| Section | What it means |
+|---|---|
+| 🧭 **Read this first** | the thing to act on before anything else. Relay it verbatim |
+| 🔴 **Broken** | the app answered with an error, or the suite failed under `--suite` |
+| ⛔ **To decide** | drift and findings a person must judge |
+| 🔧 **Ready to repair** | proposed rewrites to the suite's selectors — **proposed, never applied** |
+| 🔍 **Not seen** | pages not explored, not mapped, not compared, or the suite never visits |
+
+Exit codes: `0` answered · `1` something failed · `2` **could not answer**. Reading a `2` as a
+`1` turns an unanswered question into a red build.
+
+## 5. Never do this
+
+1. **Never run `ia-qa-heal login` or `ia-qa-heal ui` yourself.** Both wait for a person at a
+   browser; in your shell they hang. Give the human the command.
+2. **Never call a first tour a pass.** It says *Baseline established* because nothing was
+   compared — there was nothing to compare with.
+3. **Never drop the "Not seen" section** from a green report. A tour that measured a third of
+   the app and found nothing is not a green app, and that section is where the denominator is.
+4. **Never apply the repairs** in *Ready to repair* without the human reviewing them. pal never
+   edits a test file; neither should you on its behalf.
+5. **Never add `--suite` without asking.** It runs *their* test command on *their* machine, and
+   a full suite can be twenty minutes. If they want a shorter one, it goes in their config as
+   `"pal": { "testCommand": "…" }` — read from the file, never from your flag.
+6. **Never re-run a tour to "get a cleaner result".** Only one runs per project; a second is
+   refused while the first is alive. Follow with `status`.
+7. **Never promote a baseline to clear a BLOCK.** `ia-qa-pal accept <page…>` exists for drift a
+   **person** reviewed and decided was intended. It is CLI-only and has no MCP tool on purpose.
+8. **When every page failed to map, stop and read the cause.** pal refuses before running the
+   suite in that case and names it — usually the session. Do not re-run; run
+   `npx -p @ia-qa/self-healing ia-qa-heal session --check`, which separates *expired* (log in
+   again) from *wrong-host* (the session and the app's URL are different applications — logging
+   in again changes nothing) from *rotated*. If the human only wanted the coverage measurement,
+   `ia-qa-pal tour --suite-only` runs their suite without any of the comparison.
+
+## 6. What leaves the machine
+
+Nothing. pal drives a local headless browser against the app the user configured, and runs
+their own test command only when asked. No LLM is called and nothing is sent to ia-qa.com.
+
+The one secret it can touch is a session file — live cookies, gitignored on creation. Never
+print it, never copy it, never commit it.
+
+## 7. Where each thing actually lives
+
+| Path | What it is |
+|---|---|
+| `.ia-qa/config.json` | the project: URL, pages, login, test command |
+| `.ia-qa/mapping/`, `.ia-qa/baseline/` | the contracts, and the reference they are compared to |
+| `.ia-qa/pal/run.json` | the live tour: phase, progress, then the final report |
+| `.ia-qa/pal/history.jsonl` | one line per finished tour |
+| `.ia-qa/session.json` | **secret** — live cookies |
+
+For anything about locators, verdicts or repairs themselves, the deeper instructions are in
+`@ia-qa/self-healing`: `npx -p @ia-qa/self-healing ia-qa-heal skill --print`.