npm - mjolnir-qa - Versions diffs - 0.5.12 → 0.5.14 - Mend

mjolnir-qa 0.5.12 → 0.5.14

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 (6) hide show

package/README.md CHANGED Viewed

@@ -12,15 +12,23 @@ pipelines, reports a worthiness score, and shows exactly where trust breaks.
 [![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
 ```
 **Are your tests worthy of trust?**
-[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)
+[See it work](#-see-it-work) · [Quickstart](#-quickstart) · [Who it's for](#-who-is-this-for) · [Why not a linter](#-mjölnir-is-not-another-linter) · [What it verifies](#-what-mjölnir-verifies) · [Scoring](#-how-the-score-works) · [Runtime evidence](#-runtime-evidence) · [CI](#-ci-integration) · [Agents & MCP](#-works-with-your-agent) · [Docs](#-documentation) · [Contributing](#-contributing)
+<details>
+<summary>Read this in another language — 22 translations</summary>
+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)
+English is canonical. Translations are machine-assisted and may lag behind
+it; `npm run docs:translations` reports how far.
+</details>
 </div>
@@ -28,15 +36,48 @@ npx mjolnir-qa@latest
 ## 🎬 See it work
+<!-- Plays inline on github.com only: <video> is rendered for GitHub's own
+     user-content CDN, never for a repo-relative path. The <a> below is the
+     fallback for every other renderer (npm, mirrors, offline clones). -->
 <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" />
+  <video
+    src="https://github.com/user-attachments/assets/0e1af1e4-1e27-4c1c-9ec4-2717d194df05"
+    poster="https://raw.githubusercontent.com/Sergey-Bar/Mjolnir/main/assets/video/mjolnir-demo-poster.png"
+    controls
+    muted
+    playsinline
+    width="900"></video>
+</p>
+<p align="center">
+  <strong>42 seconds</strong> — one false-green CI gate: found, fixed,
+  re-proved, then handed to an agent.
+  <a href="assets/video/mjolnir-demo.mp4">Download the 1440p MP4</a> if the
+  player above doesn't load.
+</p>
+<sub>Every frame is real CLI output — the 75 → 90 score change is a real
+re-scan after applying the fix the tool itself printed, never a mockup.
+Rendered by `npm run docs:video` from
+[`assets/video/script.demo.json`](assets/video/script.demo.json);
+[`tests/contract/video-script.spec.ts`](tests/contract/video-script.spec.ts)
+fails CI if that script stops matching what the CLI prints, or if the
+findings the video shows as fixed turn out to still be there.</sub>
+<details>
+<summary><strong>Prefer it inline?</strong> The full <code>--verbose</code> report, as an animated SVG</summary>
+<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" 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>
+[`tests/contract/demo-asset-reproducibility.spec.ts`](tests/contract/demo-asset-reproducibility.spec.ts)
+fails CI if it drifts.</sub>
+</details>
 **What just happened:**
@@ -47,28 +88,50 @@ fails CI if it drifts from what the tool prints.</sub>
    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.
+4. `mjolnir handoff` turned the findings into a remediation plan — evidence,
+   constraints and a copy-pastable prompt per finding — that Claude Code
+   (or any other agent) can work through, with the tool's own verification
+   discipline built in.
+An 89-second tour of `explain` and `forensics` is built from
+[`script.tour.json`](assets/video/script.tour.json) by `npm run docs:video`
+— not committed as an MP4 (~16MB), so check
+[Releases](../../releases) or render it yourself.
 ### 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
+  ▚ QA-CI-001 — continue-on-error masks a failing verification gate
 Severity:    error
 Confidence:  high
+Tier:        quarantine
 Evidence:    E2
-Measured FP: not yet measured — this rule ships on assumption (see docs/FP-AUDIT.md)
+QA impact:   False-green risk (FALSE-GREEN)
+Measured FP: 11% (19 hand-classified corpus verdicts)
+FP risk:     low (author estimate)
+Languages:   yaml
+Frameworks:  github-actions
 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.
+  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.
+  Example from this rule's own must-fire fixture: QA-CI-001/must-fire/masked.yml
+HOW TO VERIFY THE FIX
+  Re-run `mjolnir` on the changed file(s) — this finding should no longer
+  appear. `mjolnir --scope changed` scopes the check to just what you touched.
+Docs: mjolnir rules --md   (full catalog, this rule included)
 ```
 That is the unit of value: not a style nit, but a place where your CI is
@@ -100,6 +163,7 @@ and you're done. Everything else is optional.
 | `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 why src/a.spec.ts:42`      | Why this exact line was flagged — never a gate   |
 | `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)  |
@@ -120,19 +184,23 @@ and you're done. Everything else is optional.
 <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       |
+| 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 summary`               | CI annotations + step summary from a saved report      |
+| `mjolnir pr-comment`            | A scoped PR comment, as Markdown                       |
+| `mjolnir debt`                  | Test-debt register with a cost model                   |
+| `mjolnir handover`              | New-QA onboarding map of the suite                     |
+| `mjolnir init`                  | Detect frameworks + setup checklist (never overwrites) |
+| `mjolnir suppressions`          | List suppressed findings — governance transparency     |
+| `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             |
 </details>
@@ -153,7 +221,35 @@ Requires Node.js ≥ 22.18. Works on Windows, macOS, and Linux.
 ---
-## 🔨 What Mjölnir checks
+## ⚡ 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 | AI code review |   **Mjölnir**    |
+| -------------------------------------------------------- | :----------------: | :------------: | :------------: | :--------------: |
+| CI workflow integrity (`continue-on-error`, `\|\| true`) |         ❌         |       ❌       | only the diff  |        ✅        |
+| Cross-language (TS, Python, Java, C#) from one tool      |         ❌         |       ❌       |       ❌       |        ✅        |
+| Grades Playwright locator resilience (Selector Health)   |         ❌         |       ❌       |       ❌       |        ✅        |
+| Flags tests with no real assertions                      |   ✅ (plugin)\*    |       ❌       |   sometimes    |        ✅        |
+| Catches hard sleeps (`waitForTimeout`, `time.sleep`)     |   ✅ (plugin)\*    |       ❌       |   sometimes    |        ✅        |
+| Reads real run data for `TRUE-FLAKE` verdicts            |         ❌         |       ❌       |       ❌       |        ✅        |
+| Deterministic (same input → same output)                 |         ✅         |       ✅       |       ❌       |        ✅        |
+| Cost per scan                                            |        free        |      free      |     tokens     | **zero** (local) |
+\*`eslint-plugin-jest` (`expect-expect`) and `eslint-plugin-playwright`
+(`expect-expect`, `no-wait-for-timeout`) cover these for their respective
+frameworks.
+**Use AI review too.** It 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.
+---
+## 🔨 What Mjölnir verifies
 |     |                                                                                                                   |
 | --- | ----------------------------------------------------------------------------------------------------------------- |
@@ -164,12 +260,15 @@ Requires Node.js ≥ 22.18. Works on Windows, macOS, and Linux.
 | 🐍  | **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
 firewall.
+**The rule catalog.** Every family is collapsed below; the generated
+full catalog lives in [`docs/rules/`](docs/rules/),
+[what it checks](https://sergey-bar.github.io/Mjolnir/guide/what-it-checks),
+or `mjolnir rules --md`.
 <details>
 <summary><strong>Test Hygiene</strong></summary>
@@ -282,6 +381,29 @@ firewall.
 >
 > Per-rule pages live under [`docs/rules/`](docs/rules/).
+### Selector Health Score
+A pass rate says the suite went green today. It says nothing about whether
+it will still go green after a redesign. `mjolnir doctor:playwright` grades
+every locator in a spec file by how it finds an element — the way a user
+identifies it (role, label, text), an explicit contract (`data-testid`), or
+a structural accident (CSS chains, XPath) — and scores the file 0–100:
+```text
+  ▚ SELECTOR HEALTH
+e2e/login.spec.ts
+  [█████████████░░░░░░░]  65 / 100
+  role/text: 1 · testid: 0 · css-chains: 1 ⚠ · xpath: 0
+e2e/checkout.spec.ts
+  [█████████████████░░░]  86 / 100
+  role/text: 3 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
+```
+`.btn.btn-primary > div:nth-child(2)` is not a test failure today — it's a
+test failure scheduled for whenever someone touches the markup.
 ### How much of this is measured
 **78 of 99 rules carry a false-positive rate measured against real OSS code** (≥ 10 hand-classified findings each; see
@@ -295,83 +417,85 @@ Growing that number 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.
+**measured** false-positive rate — quarantine rules only run under
+`--strict`. Tiers, language maturity and the promotion/demotion rules:
+[rule lifecycle](https://sergey-bar.github.io/Mjolnir/reference/rule-lifecycle).
+### What it can't tell you
+A tool that claims your tests are lying should be blunt about its own
+limits:
+- **It does not run your tests.** It reads your code and, when you point
+  it at one, a run report. A clean scan is not a passing suite.
+- **It cannot tell you an assertion is _wrong_.** `expect(total).toBe(41)`
+  is a perfectly healthy-looking test. Mjölnir finds tests that can't fail
+  and pipelines that can't go red — not tests that check the wrong thing.
+- **A 100 is not proof of a good suite.** It means none of these 99 rules
+  fired. Coverage of your actual risk is a different question, and this
+  tool does not pretend to answer it.
+- **21 of 99 rules ship on an estimate**, not a measured rate — and they
+  say so, per rule, in `mjolnir explain`.
+- **E1 findings are heuristics.** They are positioned to be worth reading,
+  not to be applied blindly; the evidence level is attached to every
+  finding precisely so you can tell the difference.
+- **An empty repo scores `null`, never 100.** "Unknown" is a verdict here.
+### We run it on ourselves
+Every CI run scans this repository with the build produced by that same
+run, and the gate fails on **any** error-severity finding — but also on a
+_partial_ scan or a crashed rule, because a truncated self-scan that
+reports nothing is exactly the false green this project exists to catch.
+The result is uploaded as a build artifact on every run.
 ---
-## How the score works
+## 📊 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>
+<table>
+<tr>
+<td width="46%" valign="top" align="center">
-<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>
+<img src="assets/readme/score-gauge.svg" alt="The hammer sweeping every score from 0 to 100 — cracked below 50 (UNWORTHY), strained 50-79 (NEEDS WORK), charged 80-99 (WORTHY), forged at 100 (FORGED) — then holding on FORGED before it loops" width="270" />
-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**
+**What the score means**
-| Score   | Verdict          |
-| ------- | ---------------- |
-| 100     | ⚡ **FORGED**    |
-| ≥ 80    | ✓ **WORTHY**     |
-| 50 – 79 | ⚠ **NEEDS WORK** |
-| < 50    | ✖ **UNWORTHY**   |
+</td>
+<td width="54%" valign="top" align="center">
-**Evidence levels** — every finding carries one; it sets the finding's
-weight in the score:
+<img src="assets/readme/terminal-hero.svg" alt="Mjölnir's deduction breakdown — WORTHINESS 75/100 NEEDS WORK, a diagnostics-by-category bar chart, the per-severity deduction box, and a FIX THIS FIRST list" width="330" />
-| 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             |
+**Where the points went**
-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.
+</td>
+</tr>
+</table>
-An empty repo scores `null`, never a fake 100 — see [Trust model](#trust-model).
+<sub>Left: every score 0–100 through the real `deriveScoreState`/`renderHammer`
+(`npm run docs:gauge`) — the hammer has four real states, so it snaps at the
+exact thresholds rather than faking an in-between shape. Right: a real strict
+scan of `examples/demo-repo` (`npm run docs:hero`), excerpted to the deduction
+block. Both are drift-locked
+([gauge](tests/contract/score-gauge-asset-reproducibility.spec.ts) ·
+[breakdown](tests/contract/hero-asset-reproducibility.spec.ts)).</sub>
----
-## 🎭 Selector Health Score
-The headline metric for Playwright suites — how resilient your locators are:
-```text
-▚ SELECTOR HEALTH — e2e/checkout.spec.ts
+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.
-  [█████████████████░░░]  83 / 100
-  role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
-```
+Each band also carries an evidence level: **100/FORGED** is **E2**
+(deterministic defect, full deduction), **≥ 80/WORTHY** and **50–79/NEEDS
+WORK** findings are mostly **E1** (heuristic pattern, half deduction), and
+**E0** (observation) findings cost nothing — info only. The tagline "we
+prove it" refers to this system: E2 findings are structural proof; E1
+findings are correctly-positioned warnings, not formal proofs.
-Role-based locators score full credit. CSS class chains and XPath tank the
-score — they break on any DOM refactor without telling you which behavior
-regressed.
+**No false proof.** We'd rather say "unknown" than "verified" — an empty
+repo scores `null`, never a fake 100. Full method:
+[docs/SCORING.md](docs/SCORING.md) ·
+[scoring guide](https://sergey-bar.github.io/Mjolnir/guide/scoring).
 ---
@@ -385,7 +509,7 @@ mjolnir forensics ./test-results/
 ```
 ```text
-▚ FLAKINESS LEADERBOARD
+  ▚ FLAKINESS LEADERBOARD
 3 tests · 1 failed · 1 flaky · 1 retried
@@ -400,60 +524,6 @@ test. It gets flagged `TRUE-FLAKE` regardless of the final green checkmark.
 ---
-## ⚡ 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, runs in 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:
@@ -485,46 +555,46 @@ ref with `--base <ref>`.
 ---
-## Configuration
+## 🧠 Works with your agent
-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.
+Findings are only worth something if something acts on them. Mjölnir hands
+its evidence to a coding agent three ways — none of them "paste the
+terminal output and hope".
-| 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))                                                                                                              |
+| Command           | What the agent gets                                                                                                                                                           |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mjolnir mcp`     | Runs as an [MCP](https://modelcontextprotocol.io) server over stdio — `scan`, `explain` and `diff` become tools Claude Code, Claude Desktop or any MCP client can call.       |
+| `mjolnir handoff` | A saved `--json` report becomes a deterministic Markdown remediation plan: what was detected, the evidence boundary per finding, what must **not** change, and how to verify. |
+| `mjolnir install` | Writes the agent instruction surfaces your repo already has (e.g. `.claude/commands/`), so the agent knows to re-scan before it claims it's done.                             |
+Add the MCP server to Claude Code:
+```bash
+claude mcp add mjolnir -- npx -y mjolnir-qa@latest mcp
+```
+Or to any client that takes an `mcpServers` block:
 ```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"
-    }
-  ]
+  "mcpServers": {
+    "mjolnir": { "command": "npx", "args": ["-y", "mjolnir-qa@latest", "mcp"] }
+  }
 }
 ```
-- **`.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).
+Everything a machine consumes — MCP tool results, `--json`, SARIF — comes
+off one canonical result under a versioned, additive-only schema, so a
+consumer never has to reconstruct semantics for itself:
+[the machine contract](docs/machine-contract.md) (`contractVersion: 1`).
-`ignore` entries also power the standalone `mjolnir suppressions` command,
-which lists what's currently suppressed and when each entry expires.
+**The guardrail matters more than the convenience.** Every finding in a
+handoff carries its evidence boundary: **E2** says _deterministic — check
+the location and apply the fix_; **E1** says _REQUIRES CONFIRMATION — the
+observation alone does not prove the defect_. An agent that "fixes" E1
+findings blindly, or suppresses a rule to get a green scan, is doing the
+exact thing this tool exists to catch — so the artifact says so, in the
+prompt, next to the finding.
 ---
@@ -545,77 +615,25 @@ are immutable once shipped and never reused.
 ---
-## Trust model
-- **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 & execution gate** — plugins are npm packages declared
-  under `"plugins"`; JS modules live in `mjolnir-rules/*.mjs`. There is
-  **no sandbox**: plugin code runs with full Node privileges, the same
-  trust model as ESLint or Vitest plugins. Because of that, code execution
-  is **opt-in at every scan**: pass `--enable-plugins` (or set
-  `MJOLNIR_ENABLE_PLUGINS=1`) or the sources are NOT loaded — a loud
-  stderr notice lists exactly what was skipped. Scanning untrusted code
-  never executes it. JSON rule manifests (`mjolnir-rules/*.json`) are
-  unaffected: they declare regex patterns and execute no code by design.
-  Core rule-ID prefixes are reserved and rejected from plugins and
-  external rules 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>`.
----
+## 🔒 Trust model
-## 🏗️ Architecture
+**Local-first, zero telemetry, no false proof.** Scanning untrusted code
+never executes it.
-<details>
-<summary>Expand tree</summary>
-```
-mjolnir/
-├── src/
-│   ├── engine/          # LanguageAdapter interface + rule runner
-│   ├── adapters/        # typescript · python · java · csharp · github-actions
-│   ├── rules/           # rules across 8 families + the measured-FP table
-│   ├── playwright/      # Selector Health Score engine
-│   ├── discovery/       # workspace, frameworks, ignore resolution
-│   ├── scope/           # git merge-base changed-scope engine
-│   ├── scorer/          # transparent deduction table + prioritization
-│   ├── reporter/        # terminal · JSON · SARIF 2.1 · Mermaid
-│   ├── forensics/       # run-data ingestion · flake verdicts · triage
-│   ├── 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
-```
-</details>
+The one part that changes how you invoke the tool: **plugins are not
+sandboxed.** JS plugins (`mjolnir-rules/*.mjs`, or npm packages under
+`"plugins"`) run with full Node privileges — the same trust model as
+ESLint or Vitest plugins — so loading them is opt-in **per scan**: without
+`--enable-plugins` (or `MJOLNIR_ENABLE_PLUGINS=1`) the sources are not
+loaded, and a stderr notice lists exactly what was skipped. JSON rule
+manifests declare regex patterns and execute no code by design. Core
+rule-ID prefixes are reserved, so a plugin cannot impersonate one.
-- **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.
+Scoring math, rule lifecycle, architecture and the tree-sitter roadmap:
+[docs/SCORING.md](docs/SCORING.md) ·
+[docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md) ·
+[CONTRIBUTING.md](CONTRIBUTING.md) ·
+[docs site](https://sergey-bar.github.io/Mjolnir/).
 ---
@@ -641,7 +659,7 @@ mjolnir/
 **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).
+newer — read them through the [maturity table](https://sergey-bar.github.io/Mjolnir/reference/rule-lifecycle).
 Honest scope, no invented dates: the [public roadmap](https://sergey-bar.github.io/Mjolnir/reference/roadmap).
 ---