npm - mjolnir-qa - Versions diffs - 0.4.0 → 0.5.2 - Mend

mjolnir-qa 0.4.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md CHANGED Viewed

@@ -1,23 +1,18 @@
 <div align="center">
-<pre>
- ╔═══════════╗
- ║           ║
-                  ╠═══════════╣    M J Ö L N I R
- ║     ║     ║
-                              ╚═════╩═════╝    VERIFICATION TRUST ENGINE
- ║
- ║
-</pre>
+<img src="assets/readme/logo.png" alt="Mjölnir — Verification Trust Engine" width="800" />
 ### Your tests are lying to you. We prove it.
-**Verification Trust Engine for QA.** Audits test suites and CI pipelines,
-reports a worthiness score, and shows exactly where trust breaks.
+**Verification Trust Engine for QA.** Mjölnir audits test suites and CI
+pipelines, reports a worthiness score, and shows exactly where trust breaks.
-[![license](https://img.shields.io/badge/license-MIT-B45309.svg?style=flat-square&labelColor=0D0D0D)](LICENSE)
-[![node](https://img.shields.io/badge/node-%E2%89%A5%2022.18-146A8C.svg?style=flat-square&labelColor=0D0D0D)](https://nodejs.org)
-[![status](https://img.shields.io/badge/status-●_ONLINE-15803D.svg?style=flat-square&labelColor=0D0D0D)](#-quickstart)
+[![npm](https://img.shields.io/npm/v/mjolnir-qa.svg?style=flat-square&color=C9A227&labelColor=0B0F17)](https://www.npmjs.com/package/mjolnir-qa)
+[![ci](https://img.shields.io/github/actions/workflow/status/Sergey-Bar/Mjolnir/ci.yml?branch=main&style=flat-square&label=ci&labelColor=0B0F17)](https://github.com/Sergey-Bar/Mjolnir/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-C9A227.svg?style=flat-square&labelColor=0B0F17)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A5%2022.18-2E8C7F.svg?style=flat-square&labelColor=0B0F17)](https://nodejs.org)
+English | [简体中文](README.zh.md) | [繁體中文](README.zht.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Dansk](README.da.md) | [日本語](README.ja.md) | [Polski](README.pl.md) | [Русский](README.ru.md) | [Norsk](README.no.md) | [Português (Brasil)](README.br.md) | [ไทย](README.th.md) | [Türkçe](README.tr.md) | [Українська](README.uk.md) | [বাংলা](README.bn.md) | [Ελληνικά](README.gr.md) | [Tiếng Việt](README.vi.md) | [עברית](README.he.md) | [العربية](README.ar.md) | [Bosanski](README.bs.md)
 ```bash
 npx mjolnir-qa@latest
@@ -25,104 +20,154 @@ npx mjolnir-qa@latest
 **Are your tests worthy of trust?**
-[Quickstart](#-quickstart) · [Rules](#-the-rules) · [Selector Health](#-selector-health-score) · [Runtime Evidence](#-runtime-evidence) · [CI Integration](#-ci-integration) · [Contributing](#-contributing)
+[See it work](#-see-it-work) · [Quickstart](#-quickstart) · [What it checks](#-what-mjölnir-checks) · [Scoring](#how-the-score-works) · [CI](#-ci-integration) · [Configuration](#configuration) · [Docs](#-documentation)
 </div>
 ---
-## 🔨 What is Mjölnir?
+## 🎬 See it work
-|     |                                                                                                                |
-| --- | -------------------------------------------------------------------------------------------------------------- |
-| ⚖️  | **Worthiness Score** — one number, transparent deduction table, no black box                                   |
-| 🎭  | **Selector Health Score** — grades your Playwright locators, not just your pass rate                           |
-| 🔬  | **Runtime forensics** — reads real Playwright/JUnit run data to catch `TRUE-FLAKE`, not just static guesses    |
-| 🚨  | **CI-integrity rules** — catches `continue-on-error`, `\|\| true`, and other false-green tricks                |
-| 🐍  | **Multi-language** — TypeScript/Playwright, Python/pytest, Java, and C#/.NET today, one adapter away from more |
-| 🔒  | **Local-first** — zero network calls while scanning, zero telemetry, runs in seconds                           |
+<p align="center">
+  <img src="assets/readme/demo.svg" alt="Mjölnir's full --verbose report on a demo repo: WORTHINESS 75/100 NEEDS WORK, a diagnostics-by-category breakdown, a FIX THIS FIRST list, and every finding with its rule ID and line number across CI, Playwright, test-hygiene and Python rules" width="900" />
+</p>
----
+<sub>The complete `npx mjolnir-qa ./examples/demo-repo --verbose` output,
+rendered from the actual reporter — nothing trimmed. Regenerated by
+`npm run docs:demo`;
+[`tests/demo-asset-reproducibility.spec.ts`](tests/demo-asset-reproducibility.spec.ts)
+fails CI if it drifts from what the tool prints.</sub>
-## ⚡ Mjölnir is not another linter
+**What just happened:**
+1. Mjölnir discovered the Playwright specs, its config, the CI workflow and
+   a Python test file — four languages/formats, one pass.
+2. It found evidence that weakens trust in the suite — a `continue-on-error`
+   masking a job, a `|| true` swallowing an exit code, hard sleeps, a
+   brittle selector, hardcoded staging URLs, a `networkidle` wait.
+3. It turned each into a concrete finding with a rule ID, a location and a
+   fix — and a single score you can gate a PR on.
+### One finding, up close
+Run `mjolnir explain QA-CI-001` on the first finding above and you get:
+```text
+▚▞ QA-CI-001 — continue-on-error masks a failing verification gate
-Linters tell you whether code follows rules.
-Mjölnir tells you whether your verification can be trusted.
+Severity:    error
+Confidence:  high
+Evidence:    E2
+Measured FP: not yet measured — this rule ships on assumption (see docs/FP-AUDIT.md)
-|                                                            | ESLint / SonarQube | Coverage tools | Manual review | **Mjölnir** |
-| ---------------------------------------------------------- | :----------------: | :------------: | :-----------: | :---------: |
-| Catches syntax & style bugs                                |         ✅         |       ❌       |   ✅ (slow)   |      —      |
-| Flags tests with no real assertions                        |         ❌         |       ❌       |   sometimes   |     ✅      |
-| Catches CI false-greens (`\|\| true`, `continue-on-error`) |         ❌         |       ❌       |    rarely     |     ✅      |
-| Reads **real** run data for `TRUE-FLAKE` verdicts          |         ❌         |       ❌       |      ❌       |     ✅      |
-| Grades Playwright locator resilience                       |         ❌         |       ❌       |    rarely     |     ✅      |
-| Runs in seconds, zero network calls                        |         ✅         |       ✅       |       —       |     ✅      |
+WHAT WAS FOUND (real detector output, not a mockup)
+  Job `security-scan` runs a verification gate under `continue-on-error: true`.
+WHY IT MATTERS
+  This job can fail every day and CI will still show green. The checkmark
+  on this workflow cannot be trusted.
+HOW TO FIX
+  Remove continue-on-error, or scope it to individual non-blocking steps only.
+```
+That is the unit of value: not a style nit, but a place where your CI is
+telling you something passed when it didn't.
 ---
 ## ⚡ Quickstart
+Run it against a repo for a full report and a worthiness score:
 ```bash
 npx mjolnir-qa@latest
 ```
-That's it. Zero configuration — Mjölnir detects your frameworks, finds your
-tests, and reports.
-| Command                                                | What it does                                                        |
-| ------------------------------------------------------ | ------------------------------------------------------------------- |
-| `npx mjolnir-qa@latest --scope changed`                | Only findings introduced by **your** changes — perfect for PRs      |
-| `npx mjolnir-qa@latest --json`                         | Machine-readable output                                             |
-| `npx mjolnir-qa@latest --format sarif > mjolnir.sarif` | GitHub Code Scanning integration                                    |
-| `npx mjolnir-qa@latest --format mermaid`               | Test-architecture diagram — paste into a GitHub comment or a slide  |
-| `mjolnir doctor:playwright`                            | Playwright-only deep scan + Selector Health Score                   |
-| `mjolnir forensics ./test-results/`                    | Runtime evidence — retries, true flakes, `FLAKY.md` artifact        |
-| `mjolnir triage ./test-results/`                       | The flaky-triage meeting, in 10 minutes instead of 45               |
-| `mjolnir fix --dry-run` / `fix`                        | Safe auto-fixes with proof (dry-run first)                          |
-| `mjolnir debt`                                         | Test debt register — presentable to management                      |
-| `mjolnir handover`                                     | New-QA-onboarding map of the suite                                  |
-| `mjolnir pw-report ./test-results/`                    | Playwright run summary — retries / flakes / slowest                 |
-| `mjolnir badge`                                        | Evidentiary badge (shields.io endpoint JSON)                        |
-| `mjolnir doctor`                                       | Self-audit — prove Mjölnir's own rule base is worthy                |
-| `mjolnir rules` / `rules --md`                         | Rule catalog with trust metadata (JSON or markdown)                 |
-| `mjolnir explain <RULE-ID>`                            | What/why/fix for one rule, with a real example from its own fixture |
-| `mjolnir impact [--since <ref>]`                       | What changed since a prior commit — fixes and new debt              |
+**In CI, the product is one command.** It scans only what the branch
+touched and exits non-zero on new problems:
----
+```bash
+npx mjolnir-qa@latest --scope changed
+```
-## ⚖️ Worthiness Score
+Drop that in a PR check — `mjolnir ci install` writes the workflow —
+and you're done. Everything else is optional.
-```text
-🔨 MJÖLNIR
+| Command                             | What it does                                     |
+| ----------------------------------- | ------------------------------------------------ |
+| `mjolnir`                           | Full-repo scan + worthiness score                |
+| `mjolnir --scope changed`           | Only what your branch introduced — the CI form   |
+| `mjolnir ci install`                | Generate the advisory PR workflow                |
+| `mjolnir explain QA-CI-001`         | What / why / fix + measured FP rate for one rule |
+| `mjolnir rules --unmeasured`        | The rules running on assumption, not measurement |
+| `mjolnir --json` / `--format sarif` | Machine-readable / GitHub Code Scanning          |
+| `mjolnir --strict`                  | Also run quarantine-tier rules (higher FP risk)  |
+| `mjolnir --cache`                   | Incremental re-scans via a local verdict cache   |
-WORTHINESS 80/100 — WORTHY
-████████████████████████░░░░░░
+<details>
+<summary><strong>When something's flaky</strong></summary>
-DETECTED [playwright]
+| Command                             | What it does                                        |
+| ----------------------------------- | --------------------------------------------------- |
+| `mjolnir forensics ./test-results/` | Real run data → `TRUE-FLAKE` verdicts, `FLAKY.md`   |
+| `mjolnir triage ./test-results/`    | Quarantine proposal from execution history          |
+| `mjolnir pw-report ./test-results/` | Playwright run summary — retries / flakes / slowest |
+| `mjolnir doctor:playwright`         | Playwright-only deep scan + Selector Health Score   |
-▚ FIX THIS FIRST
-+8 pts  QA-CI-001 · .github/workflows/ci.yml:48
-+3 pts  QA-TEST-004 · e2e/checkout.spec.ts:6
-```
+</details>
-The score is transparent: error −8, warning −3, info −1. Evidence-weighted
-deductions mean weak signals cost less. The terminal shows the same discounted
-numbers the score uses — no black box.
+<details>
+<summary><strong>Occasional / reporting</strong></summary>
+| Command                         | What it does                                     |
+| ------------------------------- | ------------------------------------------------ |
+| `mjolnir fix --dry-run` / `fix` | Safe auto-fixes with proof                       |
+| `mjolnir baseline` / `diff`     | Snapshot findings, then report only new/worsened |
+| `mjolnir impact --since <ref>`  | What changed since a prior commit                |
+| `mjolnir debt`                  | Test-debt register with a cost model             |
+| `mjolnir handover`              | New-QA onboarding map of the suite               |
+| `mjolnir stats`                 | Local all-time counters of fixes seen            |
+| `mjolnir badge`                 | shields.io endpoint JSON + snippet               |
+| `mjolnir rules --md`            | Full rule catalog (JSON or Markdown)             |
+| `mjolnir doctor`                | Self-audit of Mjölnir's own rule base            |
+| `mjolnir create-rule <ID>`      | Scaffold a new rule + fixtures                   |
+| `mjolnir --format mermaid`      | Test-architecture diagram for a PR comment       |
-**Verdicts:**
+</details>
-| Score   | Verdict          |
-| ------- | ---------------- |
-| ≥ 80    | ✓ **WORTHY**     |
-| 50 – 79 | ⚠ **NEEDS WORK** |
-| < 50    | ✖ **UNWORTHY**   |
+Install globally instead of `npx` if you prefer: `npm i -g mjolnir-qa`.
+Requires Node.js ≥ 22.18. Works on Windows, macOS, and Linux.
 ---
-## 📋 The Rules
+## 👥 Who is this for?
+- **QA / SDET** owning an e2e or integration suite who need evidence the
+  suite actually deserves the green checkmark it produces.
+- **Platform / DevEx** teams responsible for CI integrity and release
+  gates — the people who care that a `continue-on-error` never silently
+  turns a red pipeline green.
+- **OSS maintainers** who want a cheap, always-on verification gate that
+  runs locally and in CI with zero network calls.
+---
+## 🔨 What Mjölnir checks
+|     |                                                                                                                   |
+| --- | ----------------------------------------------------------------------------------------------------------------- |
+| ⚖️  | **Worthiness Score** — one number, transparent deduction table, no black box                                      |
+| 🎭  | **Selector Health Score** — grades your Playwright locators, not just your pass rate                              |
+| 🔬  | **Runtime forensics** — reads real Playwright/JUnit run data to catch `TRUE-FLAKE`, not just static guesses       |
+| 🚨  | **CI-integrity rules** — catches `continue-on-error`, `\|\| true`, and other false-green tricks                   |
+| 🐍  | **All four Playwright bindings** — TypeScript, Python, Java, C#/.NET — plus pytest, JUnit/TestNG and CI workflows |
+| 🔒  | **Local-first** — zero network calls while scanning, zero telemetry, runs in seconds                              |
+### The rules
 Every rule ships with must-fire **and** must-not-fire fixtures. A rule that
-fires on its own negative fixture cannot ship. That's the false-positive
+fires on its own negative fixture cannot ship — that's the false-positive
 firewall.
 <details>
@@ -145,7 +190,7 @@ firewall.
 | ID           | Rule                        | Severity |
 | ------------ | --------------------------- | -------- |
-| QA-TQUAL-001 | Mock-only verification      | warning  |
+| QA-TQUAL-001 | Mock-only verification      | info     |
 | QA-TQUAL-002 | Tautological assertion      | error    |
 | QA-TQUAL-009 | Unawaited promise assertion | error    |
 | QA-TQUAL-011 | Commented-out tests         | warning  |
@@ -160,9 +205,9 @@ firewall.
 | QA-PW-002 | Unawaited locator assertion              | error    |
 | QA-PW-003 | `page.pause()` / `test.only()` committed | error    |
 | QA-PW-004 | Brittle CSS/XPath selectors              | warning  |
-| QA-PW-005 | Business logic inside `page.evaluate()`  | warning  |
-| QA-PW-114 | Legacy element handles (`page.$`)        | warning  |
-| QA-PW-118 | `networkidle` waits (flaky by design)    | warning  |
+| QA-PW-005 | Business logic inside `page.evaluate()`  | info     |
+| QA-PW-114 | Legacy element handles (`page.$`)        | info     |
+| QA-PW-118 | `networkidle` waits (flaky by design)    | info     |
 | QA-PW-123 | Hardcoded environment URLs               | warning  |
 </details>
@@ -190,18 +235,125 @@ firewall.
 | QA-PY-002 | Skipped test (`skip`, non-strict `xfail`) | warning  |
 | QA-PY-003 | Test function with no assertions          | error    |
 | QA-PY-005 | `time.sleep()` in tests                   | warning  |
-| QA-PY-006 | Empty test body (`pass`)                  | error    |
-| QA-PY-010 | Random/time dependence without freeze     | warning  |
+| QA-PY-006 | Empty test body (`pass`)                  | info     |
+| QA-PY-010 | Random/time dependence without freeze     | info     |
 | QA-PY-012 | Tautological assertion                    | error    |
+20 Python rules total (QA-PY-001…012 pytest hygiene + QA-PY-101…108 Playwright-Python).
+</details>
+<details>
+<summary><strong>Java / JUnit · TestNG ☕</strong></summary>
+| ID        | Rule                                     | Severity |
+| --------- | ---------------------------------------- | -------- |
+| QA-JV-101 | Disabled test (`@Disabled`)              | warning  |
+| QA-JV-102 | Hard sleep (`Thread.sleep()`)            | warning  |
+| QA-JV-103 | Test method with no assertions           | error    |
+| QA-JV-105 | Playwright `waitForTimeout()` hard sleep | warning  |
+| QA-JV-106 | Brittle selector instead of role locator | warning  |
+| QA-JV-108 | Hardcoded environment URL in test        | info     |
+| QA-JV-111 | Blanket `page.route("**")` mock          | info     |
+</details>
+<details>
+<summary><strong>C# / .NET — NUnit · xUnit · MSTest 🟣</strong></summary>
+| ID        | Rule                                       | Severity |
+| --------- | ------------------------------------------ | -------- |
+| QA-CS-101 | Skipped test (`[Ignore]`, `[Fact(Skip=)]`) | warning  |
+| QA-CS-102 | Hard sleep (`Thread.Sleep` / `Task.Delay`) | warning  |
+| QA-CS-103 | Test method with no assertions             | error    |
+| QA-CS-105 | `WaitForTimeoutAsync()` hard sleep         | warning  |
+| QA-CS-106 | Brittle selector instead of role locator   | warning  |
+| QA-CS-108 | Hardcoded environment URL in test          | info     |
+| QA-CS-111 | Blanket `page.RouteAsync("**")` mock       | info     |
 </details>
-> The full live catalog — every rule with confidence, false-positive risk,
-> and autofix availability — is generated from the registry:
+> The full live catalog — every rule with tier, confidence, false-positive
+> risk, and autofix availability — is generated from the registry:
 >
 > ```bash
 > mjolnir rules --md
 > ```
+>
+> Per-rule pages live under [`docs/rules/`](docs/rules/).
+### How much of this is measured
+**74 of 99 rules carry a false-positive rate measured against real OSS code** (≥ 10 hand-classified findings each; see
+[docs/FP-AUDIT.md](docs/FP-AUDIT.md)). The other 19 ship on the author's
+estimate. Every scan footer tells you how many of the rules that _fired_
+are measured; `mjolnir rules --unmeasured` lists the ones that aren't;
+every rule's `mjolnir explain` page states its status. We publish the rate
+even when it's ugly — QA-CS-103 audits at 95% and is quarantined for it.
+Growing that 78 is the project's continuing work.
+### Rule tiers and language maturity
+Every rule is `core`, `extended`, or `quarantine`, assigned from its
+**measured** false-positive rate:
+| Tier         | Meaning                                  | Default scan | `--strict` |
+| ------------ | ---------------------------------------- | :----------: | :--------: |
+| `core`       | ≤ 10 % measured FP                       |      ✅      |     ✅     |
+| `extended`   | ≤ 30 % measured FP                       |      ✅      |     ✅     |
+| `quarantine` | above 30 %, or not yet measured (n < 10) |      ❌      |     ✅     |
+| Language        | Adapter      | Coverage today                                     |
+| --------------- | ------------ | -------------------------------------------------- |
+| TypeScript / JS | compiler AST | broadest, most measured — mostly `core`/`extended` |
+| Python / pytest | regex layer  | broad, corpus-audited — mostly `core`/`extended`   |
+| Java            | regex layer  | newer — mostly `extended`/`quarantine`             |
+| C# / .NET       | regex layer  | newer — mostly `extended`/`quarantine`             |
+TypeScript and Python have the broadest measured coverage. Java and C# ship,
+are documented, and stay out of the headline number until a real consumer
+suite (not a binding library's own tests) has been audited.
+---
+## How the score works
+<p align="center">
+  <img src="assets/readme/terminal-hero.svg" alt="Mjölnir terminal output — WORTHINESS 75/100 NEEDS WORK, a diagnostics-by-category breakdown, and a FIX THIS FIRST list" width="820" />
+</p>
+<sub>Regenerated by `npm run docs:hero`;
+[`tests/hero-asset-reproducibility.spec.ts`](tests/hero-asset-reproducibility.spec.ts)
+fails CI if it drifts from what the reporter actually prints.</sub>
+The score is transparent: **error −8, warning −3, info −1**, then normalized
+by suite exposure (deductions per test declaration). Evidence-weighted
+deductions mean weak signals cost less. The terminal shows the same
+discounted numbers the score uses — no black box. Full method:
+[docs/SCORING.md](docs/SCORING.md).
+**Verdicts**
+| Score   | Verdict          |
+| ------- | ---------------- |
+| ≥ 80    | ✓ **WORTHY**     |
+| 50 – 79 | ⚠ **NEEDS WORK** |
+| < 50    | ✖ **UNWORTHY**   |
+**Evidence levels** — every finding carries one; it sets the finding's
+weight in the score:
+| Level | Meaning              | Score impact     | Example                                            |
+| ----- | -------------------- | ---------------- | -------------------------------------------------- |
+| E2    | Deterministic defect | Full deduction   | `.only` committed — structurally provable          |
+| E1    | Heuristic pattern    | Half deduction   | Regex-matched `sleep()` — strong signal, not proof |
+| E0    | Observation          | Zero (info only) | Reported but never gates CI or deducts             |
+Most rules are **E1**. The tagline "we prove it" refers to this system:
+E2 findings are structural proof; E1 findings are correctly-positioned
+warnings, not formal proofs.
+An empty repo scores `null`, never a fake 100 — see [Trust model](#trust-model).
 ---
@@ -222,7 +374,7 @@ regressed.
 ---
-## 🔬 Runtime Evidence
+## 🔬 Runtime evidence
 Static flakiness detection is guessing. Mjölnir reads **real execution
 data** — Playwright JSON reports and JUnit XML from any runner:
@@ -247,7 +399,61 @@ test. It gets flagged `TRUE-FLAKE` regardless of the final green checkmark.
 ---
-## 🤖 CI Integration
+## ⚡ Mjölnir is not another linter
+Linters tell you whether code follows rules. Mjölnir tells you whether your
+verification can be trusted.
+|                                                          | ESLint / SonarQube | Coverage tools | Manual review | **Mjölnir** |
+| -------------------------------------------------------- | :----------------: | :------------: | :-----------: | :---------: |
+| CI workflow integrity (`continue-on-error`, `\|\| true`) |         ❌         |       ❌       |    rarely     |     ✅      |
+| Cross-language (TS, Python, Java, C#) from one tool      |         ❌         |       ❌       |      ❌       |     ✅      |
+| Grades Playwright locator resilience (Selector Health)   |         ❌         |       ❌       |    rarely     |     ✅      |
+| Flags tests with no real assertions                      |   ✅ (plugin)\*    |       ❌       |   sometimes   |     ✅      |
+| Catches hard sleeps (`waitForTimeout`, `time.sleep`)     |   ✅ (plugin)\*    |       ❌       |   sometimes   |     ✅      |
+| Runs in seconds, zero network calls while scanning       |         ✅         |       ✅       |       —       |     ✅      |
+\*`eslint-plugin-jest` (`expect-expect`) and `eslint-plugin-playwright`
+(`expect-expect`, `no-wait-for-timeout`) cover these for their respective
+frameworks.
+**Runtime analysis** is a separate category from static linting:
+|                                               | Playwright retry reporter | Allure / ReportPortal | **Mjölnir forensics** |
+| --------------------------------------------- | :-----------------------: | :-------------------: | :-------------------: |
+| Reads real run data for `TRUE-FLAKE` verdicts |         partial\*         |     partial (tag)     |          ✅           |
+| Flaky-triage report from execution history    |            ❌             |          ✅           |          ✅           |
+| Integrates with static worthiness score       |            ❌             |          ❌           |          ✅           |
+\*Playwright tracks retries internally but does not produce a standalone
+flakiness report with verdict labels.
+---
+## 🤖 Why not just use AI code review?
+Different problem, different layer. AI review can spot a suspicious test
+change in a diff; it does not prove the verification system as a whole is
+trustworthy — and it only sees the diff you show it.
+|                                       | AI code review (Copilot, etc.) |         **Mjölnir**         |
+| ------------------------------------- | :----------------------------: | :-------------------------: |
+| Cost per scan                         | Tokens (scales with diff size) | **Zero** (local, installed) |
+| Sees the whole suite + all CI configs |  Only the PR diff you show it  | **Everything, every time**  |
+| Deterministic (same input → same out) |     ❌ (non-deterministic)     |           **✅**            |
+| Catches patterns dormant for months   |  Only if it's in the context   |  **✅** (scans all files)   |
+| Remembers findings between runs       | ❌ (no memory across sessions) |  **✅** (baseline + diff)   |
+| Runs without human triggering         |      Needs a PR or prompt      | **✅** (CI hook, 3 seconds) |
+**Use both.** AI catches nuance, intent, and design flaws no regex can
+find. Mjölnir catches the structural patterns AI overlooks because they
+look "intentional" — a committed `.only`, a swallowed exit code, a
+`continue-on-error` on a test job. Those aren't bugs that need reasoning;
+they're facts that need scanning.
+---
+## 🤖 CI integration
 One command generates a PR workflow — advisory by default, never blocking:
@@ -264,48 +470,108 @@ Or wire it into GitHub Code Scanning natively via SARIF:
     sarif_file: mjolnir.sarif
 ```
+Editor and pipeline setup for SARIF: [docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md).
+### Changed-scope coverage
+`--scope changed` attributes findings to lines added in your branch vs the
+merge-base with `main`. It covers test files (`*.spec.*`, `*.test.*`) plus
+GitHub workflow files and Playwright configs in the diff. When the
+merge-base can't be resolved — shallow clone, detached HEAD, non-git
+target, different default branch — it degrades honestly: findings fall
+back to full-file attribution and the report says so. Override the base
+ref with `--base <ref>`.
 ---
-## 🛡️ Trust Model
+## Configuration
+Mjölnir is zero-config. An optional `mjolnir.config.json` (or
+`.mjolnir.json`) at the repo root tunes severity, gating and scope — it
+never changes detection semantics.
+| Key                 | Type                                 | Effect                                                                                                                                                                   |
+| ------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `exclude`           | `string[]`                           | Extra ignore globs (gitignore subset), on top of the built-in defaults                                                                                                   |
+| `gate`              | `"advisory" \| "error" \| "warning"` | Which severities exit non-zero (default `error`; `advisory` never blocks)                                                                                                |
+| `severityOverrides` | `{ "<RULE-ID>": severity }`          | Re-rank a rule's findings for your repo                                                                                                                                  |
+| `ignore`            | `IgnoreEntry[]`                      | Suppress findings — **`reason` is required**; entries expire after 90 days (an explicit `expires` date, or the config file's last-modified time for entries without one) |
+| `plugins`           | `string[]`                           | Third-party rule packages (see [Trust model](#trust-model))                                                                                                              |
+```json
+{
+  "gate": "error",
+  "exclude": ["legacy/**"],
+  "severityOverrides": { "QA-PW-118": "warning" },
+  "ignore": [
+    {
+      "ruleId": "QA-TEST-004",
+      "files": ["e2e/legacy-login.spec.ts"],
+      "reason": "Third-party widget needs a settle delay; tracked in JIRA-4821",
+      "expires": "2026-12-31"
+    }
+  ]
+}
+```
-- **Local-first** — zero network calls during scanning. Ever.
-- **No false proof** — we'd rather say "unknown" than "verified". An empty
-  repo gets `score: null`, never a fake 100.
-- **Transparent scoring** — public deduction constants: error −8, warning −3,
-  info −1. No black box. Verdict thresholds: **≥80 WORTHY**, **50–79 NEEDS
-  WORK**, **<50 UNWORTHY**.
-- **Evidence-weighted deductions** — every finding carries an evidence level:
-  **E2** (deterministic defect, full deduction), **E1** (heuristic pattern,
-  half deduction), **E0** (observation — reported but costs nothing and never
-  gates CI).
-- **Partial honesty** — if analysis was cut short, the output says so.
-  Never "complete" when it isn't.
-- **QA-native language** — findings speak your vocabulary:
-  `FALSE-GREEN`, `FLAKY-RISK`, `BLOCKS-RELEASE`, `HYGIENE`.
-- **FP firewall** — detection runs on a comment/string-free view of the code
-  (TypeScript rules use the compiler AST): a pattern inside a prose comment
-  or a doc-example string is documentation, not a finding.
+- **`.mjolnirignore`** — a plain gitignore-style file for path exclusions,
+  same dialect as `exclude`. Use it for machine-wide noise; use `exclude`
+  when the list belongs in version control alongside the rest of the config.
+- **CLI overrides** — `--strict` (include quarantine rules), `--width <cols>`
+  and `--ascii` / `--no-ascii` (terminal rendering), `--tone blunt`
+  (blunter messages), `--max-duration <sec>` (bounded partial scan).
+- Rule suppression and deprecation lifecycle: [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md).
+`ignore` entries also power the standalone `mjolnir suppressions` command,
+which lists what's currently suppressed and when each entry expires.
 ---
-## 🔌 Plugin Trust Model
+## 📐 Exit codes & contracts
+Frozen — safe to build CI logic on:
+| Exit code | Meaning                                                         |
+| --------- | --------------------------------------------------------------- |
+| `0`       | Clean — no findings at or above the gate                        |
+| `1`       | Findings at or above the gate                                   |
+| `2`       | Partial scan (time budget hit, unreadable files) — never blocks |
+| `10`      | Usage error (bad flag, missing target)                          |
+| `20`      | Internal error                                                  |
-Plugins are npm packages you declare in `mjolnir.config.json`. There is **no
-sandbox**: plugin code executes with full Node privileges against the scanned
-tree — the same trust model as ESLint or Vitest plugins. Only install plugins
-you'd trust as devDependencies. Core rule-ID prefixes (`QA-TEST`, `QA-TQUAL`,
-`QA-PW`, `QA-CI`, `QA-PY`, `QA-ENV`, `QA-JV`, `QA-CS`) are reserved and
-rejected from plugins to prevent spoofing.
+The JSON/SARIF report is `schemaVersion: 1`. Rule IDs (`QA-<FAMILY>-NNN`)
+are immutable once shipped and never reused.
 ---
-## 🔍 Changed-Scope Coverage
+## Trust model
-`--scope changed` attributes findings to lines added in your branch vs the
-merge-base with `main`. It covers test files (`*.spec.*`, `*.test.*`) plus
-GitHub workflow files and Playwright configs changed in the diff. On shallow
-clones or non-git targets it degrades honestly: findings fall back to
-full-file attribution and the report says so.
+- **Local-first** — zero network calls during scanning. Ever. Zero telemetry.
+- **No false proof** — we'd rather say "unknown" than "verified". An empty
+  repo gets `score: null`, never a fake 100.
+- **Partial honesty** — if analysis was cut short, the output says so.
+  Never "complete" when it isn't.
+- **FP firewall** — detection runs on a comment/string-free view of the code
+  (TypeScript rules use the compiler AST): a pattern inside a prose comment
+  or a doc-example string is documentation, not a finding.
+- **Measured, not asserted** — only rules with a false-positive rate from
+  real OSS code ship in the headline tiers (see
+  [How much of this is measured](#how-much-of-this-is-measured)); the scan
+  footer and `mjolnir rules --unmeasured` tell you which is which.
+- **Plugin trust** — plugins are npm packages declared under `"plugins"`.
+  There is **no sandbox**: plugin code runs with full Node privileges, the
+  same trust model as ESLint or Vitest plugins. Core rule-ID prefixes are
+  reserved and rejected from plugins to prevent spoofing.
+- **Workspace-local external rules** (folder-based, zero network) — a
+  `mjolnir-rules/` directory next to the scan target loads custom rules:
+  JSON files declare regex patterns (no code executed), `.mjs`/`.js`
+  modules export `rules` (full-Node trust, same as plugins). External
+  rules carry the same trust metadata as core; they can never ship in
+  the core tier (core requires a measured FP rate from the corpus
+  sidecar — a declared `tier: "core"` is clamped to `extended`), obey
+  tier caps, and are drift-checked: `mjolnir rules --md --external`
+  renders the catalog from the loaded files (provenance `external`),
+  and the matrix generator accepts `--external <root>`.
 ---
@@ -319,15 +585,16 @@ mjolnir/
 ├── src/
 │   ├── engine/          # LanguageAdapter interface + rule runner
 │   ├── adapters/        # typescript · python · java · csharp · github-actions
-│   ├── rules/           # deterministic rules across 8 families
+│   ├── rules/           # rules across 8 families + the measured-FP table
 │   ├── playwright/      # Selector Health Score engine
-│   ├── discovery/       # workspace, frameworks, safe-YAML parser
+│   ├── discovery/       # workspace, frameworks, ignore resolution
 │   ├── scope/           # git merge-base changed-scope engine
-│   ├── scorer/          # transparent deduction table
+│   ├── scorer/          # transparent deduction table + prioritization
 │   ├── reporter/        # terminal · JSON · SARIF 2.1 · Mermaid
 │   ├── forensics/       # run-data ingestion · flake verdicts · triage
-│   ├── commands/        # fix · badge · debt · handover · init · create-rule · doctor · rules-catalog · explain · impact · baseline · diff · pr-comment · stats
-│   └── integrations/    # CI workflow generator
+│   ├── config/          # mjolnir.config.json + suppressions
+│   ├── plugins/         # third-party rule loading (no sandbox)
+│   └── commands/        # every subcommand
 └── tests/
     ├── fixtures/        # must-fire / must-not-fire per rule
     └── golden/          # frozen score regression locks
@@ -335,54 +602,60 @@ mjolnir/
 </details>
-Multi-language by design: adding a language = one adapter + its rules.
-TypeScript/Playwright and Python are the most mature; Java and C#/.NET
-adapters ship a regex-based core rule family with tree-sitter WASM AST
-precision as the next step.
+- **Rules are pure functions** — `(SourceFileContext) → Finding[]`, no I/O,
+  no globals. Adding an ecosystem = one adapter + its rules.
+- **TypeScript/Playwright uses the compiler AST** (ts-morph). Python, Java
+  and C# run on a shared comment/string-masked regex layer.
+- A tree-sitter WASM AST layer for Java and C# exists and is the next
+  precision step — it is not yet wired into the synchronous scan pipeline.
 ---
-## 📦 Install
+## 📚 Documentation
+| Document                                               | What's in it                                      |
+| ------------------------------------------------------ | ------------------------------------------------- |
+| [docs/SCORING.md](docs/SCORING.md)                     | Score normalization + evidence weighting          |
+| [docs/FP-AUDIT.md](docs/FP-AUDIT.md)                   | Measured false-positive rates + method            |
+| [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md)       | Rule states, suppression, deprecation             |
+| [docs/VERSIONING.md](docs/VERSIONING.md)               | Semver policy, frozen surfaces, deprecation cycle |
+| [docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md) | SARIF output + editor/CI setup                    |
+| [docs/rules/](docs/rules/)                             | Generated per-rule catalog                        |
+| [CONTRIBUTING.md](CONTRIBUTING.md)                     | Dev setup + contribution workflow                 |
+| [SUPPORT.md](SUPPORT.md)                               | Where to ask, report and get help                 |
+| [CHANGELOG.md](CHANGELOG.md)                           | Release history                                   |
+| [SECURITY.md](SECURITY.md)                             | Vulnerability reporting                           |
-```bash
-# Run directly (recommended):
-npx mjolnir-qa@latest
+---
-# Or install globally:
-npm i -g mjolnir-qa
-```
+## 📈 Status
-Requires Node.js ≥ 22.18. Works on Windows, macOS, and Linux.
+**v0.5.x · open beta.** The JSON schema and exit codes are frozen contracts.
+TypeScript and Python have the broadest measured coverage; Java and C# are
+newer — read them through the [maturity table](#rule-tiers-and-language-maturity).
+Honest scope, no invented dates: the [public roadmap](https://sergey-bar.github.io/Mjolnir/reference/roadmap).
 ---
 ## 🤝 Contributing
-New rules are the easiest first contribution — one command scaffolds
-everything (anti-creep law enforced by the fixture harness):
+New rules are the easiest first contribution — one command scaffolds the
+rule plus its must-fire **and** must-not-fire fixtures (the generated rule
+intentionally fails its fixtures until you implement real detection — a stub
+cannot ship):
 ```bash
 mjolnir create-rule QA-PW-140 --title "Screenshot without diff bound"
 ```
-That generates the rule file plus must-fire AND must-not-fire fixture
-skeletons. The generated rule intentionally fails its fixtures until you
-implement real detection — a stub cannot ship.
-Manual path:
-1. Fork + clone, `npm install`
-2. Copy any rule folder under `src/rules/` as a template
-3. Add must-fire AND must-not-fire fixtures under `tests/fixtures/<YOUR-ID>/`
-4. `npx vitest run` — both directions green? Ship the PR.
-See [SECURITY.md](SECURITY.md) for vulnerability reporting.
+Full dev setup, the standing-gate commands, and the anti-creep / fixture
+firewall laws are in [CONTRIBUTING.md](CONTRIBUTING.md).
 ---
 <div align="center">
-**Are your tests worthy of trust?**
+**Stop shipping tests you can't trust.**
 ```bash
 npx mjolnir-qa@latest