npm - mjolnir-qa - Versions diffs - 5.0.0 → 6.0.1 - Mend

mjolnir-qa 5.0.0 → 6.0.1

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

package/CHANGELOG.md +3292 -15
package/README.md +258 -652
package/dist/cli.d.mts +434 -741
package/dist/cli.mjs +31552 -15384
package/dist/mcp/stdio.mjs +1146 -570
package/package.json +78 -61
package/README.ar.md +0 -647
package/README.bn.md +0 -647
package/README.br.md +0 -647
package/README.bs.md +0 -647
package/README.da.md +0 -647
package/README.de.md +0 -647
package/README.es.md +0 -647
package/README.fr.md +0 -647
package/README.gr.md +0 -647
package/README.he.md +0 -647
package/README.it.md +0 -647
package/README.ja.md +0 -647
package/README.ko.md +0 -647
package/README.no.md +0 -647
package/README.pl.md +0 -647
package/README.ru.md +0 -647
package/README.th.md +0 -647
package/README.tr.md +0 -647
package/README.uk.md +0 -647
package/README.vi.md +0 -647
package/README.zh.md +0 -647
package/README.zht.md +0 -647
package/dist/rolldown-runtime-8H4AJuhK.mjs +0 -14
package/dist/scan-pipeline-DNYbnWjE.mjs +0 -2
package/dist/scan-pipeline-DT8DWAMl.mjs +0 -16501

package/README.md CHANGED Viewed

@@ -1,11 +1,10 @@
 <div align="center">
-<img src="assets/readme/hero.svg" alt="Mjölnir. Prevents release-blocking false-green." width="100%" />
+<img src="assets/readme/hero.svg" alt="Mjölnir — the verification trust engine" width="100%" />
 <br />
-Mjölnir quantifies how much you can trust your CI — and blocks releases
-when verification isn't earning its keep.
+**Mjölnir quantifies how much you can trust your CI — and blocks releases when verification isn't earning its keep.**
 <br />
@@ -13,131 +12,231 @@ when verification isn't earning its keep.
 [![downloads](https://img.shields.io/npm/dm/mjolnir-qa.svg?style=flat-square&color=1F6F7C&labelColor=0A1119)](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=0A1119)](https://github.com/Sergey-Bar/Mjolnir/actions/workflows/ci.yml)
 [![coverage](https://img.shields.io/codecov/c/github/Sergey-Bar/Mjolnir?style=flat-square&color=1F6F7C&labelColor=0A1119&label=coverage)](https://codecov.io/gh/Sergey-Bar/Mjolnir)
-[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Sergey-Bar/Mjolnir/badge)](https://scorecard.dev/viewer/?uri=github.com/Sergey-Bar/Mjolnir)
 [![license](https://img.shields.io/badge/license-MIT-1F6F7C.svg?style=flat-square&labelColor=0A1119)](LICENSE)
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2022.18-1F6F7C.svg?style=flat-square&labelColor=0A1119)](https://nodejs.org)
 ```bash
-npx mjolnir-qa@5.0.0
+npx mjolnir-qa@latest
 ```
-[See it work](#see-it-work) · [Quickstart](#quickstart) · [What it finds](#what-mjölnir-finds) · [Score](#the-worthiness-score) · [Evidence](#the-evidence-model) · [Forensics](#runtime-forensics) · [CI](#ci-integrity) · [Agents](#ai-agents) · [Security](#trust-and-security) · [Limits](#what-mjölnir-cannot-tell-you) · [Docs](#documentation)
+Pin it for reproducible CI: `npx mjolnir-qa@6.0.1`. Requires **Node.js ≥ 22.18** on Windows, macOS or Linux.
-<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)
+[**Interactive walkthrough**](https://sergey-bar.github.io/Mjolnir/) · [Docs](https://sergey-bar.github.io/Mjolnir/) · [CHANGELOG](CHANGELOG.md) · [Video](assets/video/mjolnir-demo.mp4)
-English is canonical. Translations are machine-assisted and may lag behind
-it; `npm run docs:translations` reports how far.
+</div>
-</details>
+---
-</div>
+## Release status
-<br />
+The published line is `6.0.1`, and this working tree is that line. The version table is
+[`docs/ROADMAP.yaml`](docs/ROADMAP.yaml). This document does not publish a tag or authorize a release.
-## A green check is a claim, not a proof
+---
-A green check means the pipeline did not fail. It does not mean
-the tests ran, or that they could have failed. Every one of these
-ships green — and every one of them makes your release untrustworthy:
+## The problem: a green check is a claim, not proof
-- a committed `.only` that ran 3 tests instead of 900
-- `continue-on-error: true` on the job that was supposed to gate
-- `|| true` after the test command
-- a test that asserts nothing, or has an empty body
-- a retry wrapper that turns a real failure into a lucky pass
-- a report the workflow uploads but never generated
-- a hard sleep holding a race condition together
+A green check means the pipeline did not fail. It does **not** mean the tests ran, or that they could have failed.
-None of them turns the pipeline red, and each one looks deliberate
-in review. That is why they survive. **They are the reason releases ship bugs.**
+```yaml
+# These all ship green. None earned it.
+steps:
+  - run: npm test || true # exit code swallowed (QA-CI-002)
+  - run: npm test | tee test.log # exit code lost without pipefail (QA-CI-009)
+```
-Here is Mjölnir reading a real one:
+Mjölnir reads your test suite, your CI workflows, and (when available) the report of a real run. It reports every finding with a **trust level** (L0–L5, where L3+ requires a real run) and a **measured false-positive rate** where corpus evidence exists.
 <p align="center">
-  <img src="assets/readme/scan.svg" alt="The demo repository's CI workflow, read line by line. Mjölnir flags each finding at the line it reported, with its rule, what is wrong, its evidence level and its measured false-positive rate." width="800" />
+  <img src="assets/readme/scan.svg" alt="Mjölnir reads a workflow line by line, flagging each finding with its rule, evidence level, and measured FP rate." width="800" />
 </p>
-<sub>Every finding the demo scan reported for this workflow, at the line it
-reported. Generated by `npm run docs:readme-brand` from
-[`demo-report.json`](assets/readme/demo-report.json) and drift-locked in CI.</sub>
-**Strict mode.** The most aggressive detections — `.only`, `continue-on-error`,
-empty tests, retry abuse — live in the quarantine tier. They run only
-under `--strict` and are capped to `info` severity: they flag, they never
-gate. The default scan (`npx mjolnir-qa@5.0.0` without `--strict`)
-covers core and extended rules only. Add `--strict` when you want the
-advisory layer too.
+---
-Mjölnir reads the suite, the CI workflows and, when you have one, the
-report of a real run. It does not run your tests, install your
-dependencies, or execute the code it scans. And when it has no evidence,
-it says so rather than inventing confidence:
+## See it work
-| Situation                                      | What Mjölnir reports                                     |
-| ---------------------------------------------- | -------------------------------------------------------- |
-| No test declarations found                     | Score `null`, shown as **UNKNOWN**. Never a made-up 100. |
-| No baseline or comparable revision             | **UNKNOWN**, with the reason named. Never an assumed 0.  |
-| Scan cut short (time budget, unreadable files) | **PARTIAL**, exit `2`. Never presented as clean.         |
+A real scan of [`examples/demo-repo`](examples/demo-repo):
 <p align="center">
-  <img src="assets/readme/how-it-works.svg" alt="How Mjölnir works. It reads the test suite and the CI pipeline statically, and the report of a real run when there is one. It weighs every finding by its evidence level and its trust level, where only a real run can reach L3 to L5, and produces findings, a worthiness score and a CI gate on frozen exit codes. In the agent loop, AI writes the fix and Mjölnir re-scans to prove it." width="880" />
+  <img src="assets/readme/terminal-hero.svg" alt="Mjölnir's deduction breakdown: WORTHINESS 80/100 WORTHY, the score by category, the per-severity deduction box, and a FIX THIS FIRST list" width="520" />
 </p>
-<sub>Composed for this page and shown at 1:1. Generated by
-`npm run docs:readme-brand` and drift-locked in CI; the score, counts and
-rule ID come from [`script.demo.json`](assets/video/script.demo.json),
-[`demo-report.json`](assets/readme/demo-report.json) and the rule
-registry, never typed by hand. The same picture as a poster:
-[`architecture.svg`](assets/readme/architecture.svg).</sub>
+<sub>Generated by `npm run docs:hero` from a real scan and drift-locked in CI. The full `--verbose` report is
+[`demo.svg`](assets/readme/demo.svg); the architecture poster is [`architecture.svg`](assets/readme/architecture.svg).</sub>
+---
+## Quickstart
+```bash
+# 1. Scan — Trust Report, exits 1 on gate findings
+npx mjolnir-qa@latest
+# 2. Block in CI — scan only what your branch changed
+npx mjolnir-qa@latest --scope changed
+# 3. Fix and re-verify — safe auto-fixes, each re-scanned to prove it landed
+mjolnir fix
+```
+**Prove the fix with a baseline, then delta:**
+```bash
+npx mjolnir-qa@latest --save-baseline   # once: writes .mjolnir/baseline.json
+# … make the fix …
+mjolnir ci verify                 # RESOLVED (gone) / NEW (introduced)
+```
+---
+## What it catches
+**<!-- census:total-rules -->79 rules<!-- /census:total-rules -->** in four families — test hygiene, test quality, Playwright and CI integrity — across TypeScript/JavaScript, Python, Java, C# and GitHub Actions YAML.
+| Family           | Example rules                                                                                                                                        |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **CI integrity** | `\|\| true` swallowing exit codes (`QA-CI-002`), `continue-on-error` on gate jobs (`QA-CI-001`), always-success steps masking failures (`QA-CI-008`) |
+| **Test hygiene** | Committed `.only`/`fit` (`QA-TEST-001`), tests with no assertions (`QA-TEST-003`), hard sleeps (`QA-TEST-004`)                                       |
+| **Test quality** | Unawaited promise assertions (`QA-TQUAL-009`), tautological assertions (`QA-TQUAL-002`)                                                              |
+| **Playwright**   | Unawaited locator assertions (`QA-PW-002`), `page.pause()` committed (`QA-PW-003`), brittle selectors (`QA-PW-004`)                                  |
+| **Python**       | Skipped tests (`QA-PY-002`), `time.sleep()` (`QA-PY-005`), tautological assertions (`QA-PY-012`)                                                     |
+| **Java / C#**    | Disabled tests, hard sleeps, no assertions, brittle selectors                                                                                        |
+Full catalog: `mjolnir explain --list --md` or [what-it-checks](https://sergey-bar.github.io/Mjolnir/guide/what-it-checks). **<!-- census:measured-of-total -->73 of 79<!-- /census:measured-of-total --> rules carry a false-positive rate measured against real OSS code.** The other <!-- census:unmeasured -->6<!-- /census:unmeasured --> ship on the author's estimate and say so on each finding.
+<details>
+<summary><strong>Every rule named in this README</strong>, in one table</summary>
 <br />
-## Release status
+> `warn-only` rules run only under `--include-warn` and never gate. The severity shown is the authored severity.
+| ID           | Family     | Rule                                                         | Severity | Default scan |
+| ------------ | ---------- | ------------------------------------------------------------ | -------- | ------------ |
+| QA-TEST-001  | Hygiene    | Focused test committed (`.only`, `fit`)                      | error    | warn-only    |
+| QA-TEST-003  | Hygiene    | Test with no assertions                                      | error    | warn-only    |
+| QA-TEST-004  | Hygiene    | Hard sleep (`waitForTimeout`, `sleep()`, `delay()`)          | warning  | default      |
+| QA-TQUAL-002 | Quality    | Tautological assertion                                       | error    | warn-only    |
+| QA-TQUAL-009 | Quality    | Unawaited promise assertion                                  | error    | warn-only    |
+| QA-PW-002    | Playwright | Unawaited locator assertion                                  | error    | default      |
+| QA-PW-003    | Playwright | `page.pause()` / `test.only()` committed                     | error    | default      |
+| QA-PW-004    | Playwright | Brittle CSS/XPath selectors                                  | warning  | warn-only    |
+| QA-CI-001    | CI         | `continue-on-error` masks a failing gate                     | error    | warn-only    |
+| QA-CI-002    | CI         | `\|\| true` swallows exit codes                              | error    | default      |
+| QA-CI-008    | CI         | Always-success step masks failures                           | error    | warn-only    |
+| QA-CI-009    | CI         | Exit code not propagated (`\|` without pipefail, `;` chains) | error    | default      |
+| QA-PY-002    | Python     | Skipped test (`skip`, non-strict `xfail`)                    | warning  | default      |
+| QA-PY-005    | Python     | `time.sleep()` in tests                                      | warning  | default      |
+| QA-PY-012    | Python     | Tautological assertion                                       | error    | warn-only    |
+| QA-JV-101    | Java       | Disabled test (`@Disabled`)                                  | warning  | default      |
+| QA-CS-103    | C#         | Test method with no assertions                               | error    | default      |
-The published line is `3.0.0`; this working tree is the `4.0.0-rc.1`
-candidate. `3.0.0` must not be republished or retagged. The M26–M50 program is
-tracked in
-[`docs/ROADMAP.yaml`](docs/ROADMAP.yaml); provisional capability contracts
-are not automatically enabled or certified. Repository-owned checks pass, but
-Trust certification remains `NOT_CERTIFIED` until the protected holdout,
-real-world, platform/consumer, remote-workflow, support-matrix, and corpus
-evidence gates pass. Run `npm run m26:readiness` before treating any candidate
-as releasable. This document does not publish a tag or authorize a release.
+</details>
-## See it work
+---
-A real scan of [`examples/demo-repo`](examples/demo-repo), a small
-Playwright suite with a CI workflow. This is where its points went:
+## The Worthiness Score
 <p align="center">
-  <img src="assets/readme/terminal-hero.svg" alt="Mjölnir's deduction breakdown: WORTHINESS 80/100 WORTHY, the score by category, the per-severity deduction box, and a FIX THIS FIRST list" width="520" />
+  <img src="assets/readme/score-gauge.svg" alt="Worthiness scale: UNWORTHY 0–49, NEEDS WORK 50–79, WORTHY 80–99, FORGED 100, UNKNOWN when no tests exist." width="720" />
 </p>
-<sub>Generated by `npm run docs:hero` from a real scan and drift-locked in
-CI. The full `--verbose` report of the same scan is
-[`demo.svg`](assets/readme/demo.svg) (`npm run docs:demo`).</sub>
+Severity sets a base deduction (`error −8`, `warning −3`, `info −1`), discounted by evidence level: **E2** (deterministic proof) pays in full, **E1** (pattern) half, **E0** (observation) nothing. Normalized by suite exposure — deductions per test declaration, not per file.
+---
+## Evidence you can gate on
+| Level  | Name                | Means                                              | Deduction |
+| ------ | ------------------- | -------------------------------------------------- | --------- |
+| **E2** | Deterministic proof | The defect is present in the code as written       | Full      |
+| **E1** | Pattern evidence    | A pattern strongly tied to the defect matched      | Half      |
+| **E0** | Observation         | Worth knowing. Not a claim that anything is wrong. | Zero      |
+Static scans stop at **L2** (proven in code). Give Mjölnir a real run report (Playwright JSON, Jest/Vitest JSON, JUnit XML) and findings lift to **L3–L5** (file ran, test ran, run agrees).
+---
+## Reference
 <details>
-<summary><strong>Watch it</strong> — a scan, the fix it prints, and the re-scan that proves it</summary>
+<summary><strong>Every command</strong></summary>
 <br />
-<p align="center">
-  <a href="assets/video/mjolnir-demo.mp4">
-    <img src="assets/video/mjolnir-demo-poster.png" alt="A frame of the demo recording: npx mjolnir-qa@5.0.0 scanning the demo repository in a terminal window" width="900" />
-  </a>
-</p>
+| Command                           | What it does                                            |
+| --------------------------------- | ------------------------------------------------------- |
+| `mjolnir`                         | Trust Report: verdict, confidence, next action          |
+| `mjolnir --scope changed`         | Only what your branch introduced (CI form)              |
+| `mjolnir --blocking error`        | Exit 1 on error findings — gate releases                |
+| `mjolnir ci install`              | Write the advisory PR workflow (default)                |
+| `mjolnir ci install --gate error` | Opt into the blocking PR workflow                       |
+| `mjolnir ci verify`               | Delta against `.mjolnir/baseline.json` — RESOLVED / NEW |
+| `mjolnir ci release-trust`        | 12-dimension release assurance verdict                  |
+| `mjolnir share`                   | One self-contained HTML trust report to hand over       |
+| `mjolnir contract-verify --contract <scan.json>` | Verify a persisted machine contract against a scan |
+| `mjolnir policy` | Initialize, validate, or check policy gates |
+| `mjolnir analyze --cross-file` | Bounded cross-file analysis |
+| `mjolnir ci adapters github .` | Generate CI templates for supported providers |
-<sub>Rendered frame by frame from a real scan by `npm run docs:video`;
-never screen-recorded. Select the frame to open
-[`mjolnir-demo.mp4`](assets/video/mjolnir-demo.mp4).</sub>
+| `mjolnir mcp` | Read-only MCP tools over stdio |
+| `mjolnir explain QA-CI-001` | What, why and fix, plus measured/unmeasured state |
+| `mjolnir explain <file:line> src/a.spec.ts:42` | Why this exact line was flagged. Never gates. |
+| `mjolnir handoff` | Remediation plan for a coding agent |
+| `mjolnir --json` / `--format sarif` | Machine-readable output, GitHub Code Scanning |
+| `mjolnir --format codequality` | GitLab Code Quality report (MR widget artifact) |
+| `mjolnir --include-warn` | Also run WARN-tier rules (higher FP risk) |
+<details>
+<summary><strong>Every other command</strong> — flake triage, reporting, governance</summary>
+<br />
+| Command                   | What it does                               |
+| ------------------------- | ------------------------------------------ |
+| `mjolnir --classic`       | The pre-Trust-Report score banner render   |
+| `mjolnir explain verdict` | Why the saved scan's verdict is what it is |
+| `mjolnir explain --playwright ./test-results/` | Playwright run summary: retries, flakes, slowest |
+| `mjolnir doctor --frameworks` | Playwright-only deep scan plus Selector Health Score |
+| `mjolnir fix --dry-run` / `fix` | Safe auto-fixes, each re-scanned to prove it landed |
+| `mjolnir scan` | The whole tree. This is the default: bare `mjolnir` is the same command |
+| `mjolnir scan --scope changed` | Only what this branch changed — the PR gate |
+| `mjolnir scan --format github-summary` | CI annotations and a step summary from a report |
+| `mjolnir scan --format pr-comment` | A scoped PR comment, as Markdown |
+| `mjolnir explain --plan` | Onboarding map of the suite for a new QA engineer |
+| `mjolnir scan --suppressions` | List suppressed findings, for governance |
+| `mjolnir ci integrity` | Verify blocking CI scans and suppression policy |
+| `mjolnir doctor --frameworks` | Inspect bounded maturity with human calibration |
+| `mjolnir suppression-gate` | Enforce expiry, allowlist, and mass-suppression rules |
+| `mjolnir explain --callers` | Analyze duplicate, shared, and circular test signals |
+| `mjolnir contract-verify` | Verify a persisted machine contract artifact |
+| `mjolnir ci release-trend` | Persist and compare trust snapshots over time |
+| `mjolnir evidence-graph` | Build or query the verification evidence graph |
+| `mjolnir explain --list --unmeasured` | The rules running on assumption, not measurement |
+| `mjolnir explain --list --md` | Full rule catalog (JSON or Markdown) |
+| `mjolnir explain --list capability` | The capability registry, at provable maturity only |
+| `mjolnir doctor` | Self-audit of Mjölnir's own rule base |
+| `mjolnir stats` | Local all-time counters of fixes seen |
+| `mjolnir ci verify` | Verify the blocking CI scan and the suppression policy |
+| `mjolnir --cache` | Incremental re-scans via a local verdict cache |
+| `mjolnir --format mermaid` | Test-architecture diagram for a PR comment |
+`mjolnir help <command>` prints usage, examples and the next step for any
+of them.
 </details>
-### One finding, up close
+<details>
+<summary><strong>One finding, up close</strong> — <code>mjolnir explain QA-CI-001</code></summary>
+<br />
 Every finding answers four questions: where it is, how sure Mjölnir is,
 how often the rule is wrong, and how to fix it.
@@ -190,8 +289,7 @@ WHAT WOULD CHANGE THE VERDICT
   corroborating this file lifts its findings to L3–L5
   - a documented suppression (mjolnir.config.json) lowers the finding count
   without claiming correctness
-  - quarantine findings run only under --strict and are advisory (E0) — they can
-  never gate CI
+  - WARN-tier findings run only under --include-warn and never gate CI
 NEXT ACTION
   Fix the first occurrence, then re-run: `mjolnir --scope changed`. Every
@@ -201,208 +299,49 @@ 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)
+Docs: mjolnir explain --list --md   (full catalog, this rule included)
 ```
 That is the unit of value: one place where CI reports a pass it did not earn.
-<br />
-## Quickstart
-```bash
-npx mjolnir-qa@5.0.0
-```
-Three steps to trust your release pipeline:
-1. **Scan** — `npx mjolnir-qa@5.0.0` — scans the current directory, prints the Trust Report, exits `1` if findings at the gate
-2. **Block in CI** — `npx mjolnir-qa@5.0.0 --scope changed` — scans only changed lines, blocks PRs with error findings
-3. **Fix and re-verify** — `mjolnir fix` applies safe auto-fixes, then re-scans to prove each one landed
-Install the advisory PR workflow first, so existing trust debt cannot break
-CI on day one:
-```bash
-mjolnir ci install
-```
-After reviewing the findings or baselining existing debt, opt into blocking:
-```bash
-mjolnir ci install --gate error
-```
-| Command                                       | What it does                                                 |
-| --------------------------------------------- | ------------------------------------------------------------ |
-| `mjolnir`                                     | Trust Report: verdict, confidence, next action               |
-| `mjolnir --scope changed`                     | Only what your branch introduced (CI form)                   |
-| `mjolnir --blocking error`                    | Exit 1 on error findings — gate releases                     |
-| `mjolnir ci install`                          | Write the advisory PR workflow (default)                     |
-| `mjolnir ci install --gate error`             | Opt into the blocking PR workflow                            |
-| `mjolnir business-case`                       | Measured FP rates; a cost figure only with `--incident-cost` |
-| `mjolnir release-report`                      | Release readiness: GO, CONDITIONAL GO, or NO-GO              |
-| `mjolnir release-trust`                       | 12-dimension release assurance verdict                       |
-| `mjolnir report`                              | Findings in a Playwright-shaped file (no test outcomes)      |
-| `mjolnir diff`                                | What changed against the stored baseline, by fingerprint     |
-| `mjolnir verify`                              | Digest of what a change resolved and what it introduced      |
-| `mjolnir trend`                               | Record, show, or diff local quality snapshots                |
-| `mjolnir policy`                              | Initialize, validate, or check policy gates                  |
-| `mjolnir quarantine`                          | Review deterministic proposals (prototype)                   |
-| `mjolnir analyze --cross-file`                | Bounded cross-file analysis                                  |
-| `mjolnir ci-adapter github .`                 | Generate CI templates for supported providers                |
-| `mjolnir dashboard`                           | Generate a self-contained quality dashboard                  |
-| `mjolnir exec-report`                         | Executive KPIs and recommendations (advisory)                |
-| `mjolnir enterprise`                          | Self-hosted templates (prototype)                            |
-| `mjolnir maturity`                            | Assess maturity or display maturity levels                   |
-| `mjolnir mutation tests/mutation-report.json` | Analyze mutation reports; never promotes trust               |
-| `mjolnir mcp`                                 | Read-only MCP tools over stdio                               |
-| `mjolnir explain QA-CI-001`                   | What, why and fix, plus measured/unmeasured state            |
-| `mjolnir why src/a.spec.ts:42`                | Why this exact line was flagged. Never gates.                |
-| `mjolnir forensics ./test-results/`           | Runtime evidence from a real run                             |
-| `mjolnir trust-report`                        | Self-contained Trust Artifact (md + json)                    |
-| `mjolnir handoff`                             | Remediation plan for a coding agent                          |
-| `mjolnir --json` / `--format sarif`           | Machine-readable output, GitHub Code Scanning                |
-| `mjolnir --format codequality`                | GitLab Code Quality report (MR widget artifact)              |
-| `mjolnir --strict`                            | Also run quarantine-tier rules (higher FP risk)              |
+</details>
 <details>
-<summary><strong>Every other command</strong> — flake triage, reporting, governance</summary>
+<summary><strong>Runtime forensics</strong> — what a real run report adds</summary>
 <br />
-| Command                             | What it does                                          |
-| ----------------------------------- | ----------------------------------------------------- |
-| `mjolnir --classic`                 | The pre-Trust-Report score banner render              |
-| `mjolnir explain verdict`           | Why the saved scan's verdict is what it is            |
-| `mjolnir triage ./test-results/`    | Guided triage. Every row ends in a next action.       |
-| `mjolnir pw-report ./test-results/` | Playwright run summary: retries, flakes, slowest      |
-| `mjolnir doctor:playwright`         | Playwright-only deep scan plus Selector Health Score  |
-| `mjolnir fix --dry-run` / `fix`     | Safe auto-fixes, each re-scanned to prove it landed   |
-| `mjolnir baseline` / `diff`         | Snapshot findings, then report only new or worse      |
-| `mjolnir impact --since <ref>`      | What a commit introduced and resolved                 |
-| `mjolnir summary`                   | CI annotations and a step summary from a report       |
-| `mjolnir pr-comment`                | A scoped PR comment, as Markdown                      |
-| `mjolnir debt`                      | Test-debt register with a cost model                  |
-| `mjolnir handover`                  | Onboarding map of the suite for a new QA engineer     |
-| `mjolnir init`                      | Detect frameworks, print a setup checklist            |
-| `mjolnir suppressions`              | List suppressed findings, for governance              |
-| `mjolnir ci-integrity`              | Verify blocking CI scans and suppression policy       |
-| `mjolnir framework-maturity`        | Inspect bounded maturity with human calibration       |
-| `mjolnir suppression-gate`          | Enforce expiry, allowlist, and mass-suppression rules |
-| `mjolnir cross-file`                | Analyze duplicate, shared, and circular test signals  |
-| `mjolnir contract-verify`           | Verify a persisted machine contract artifact          |
-| `mjolnir trust-trend`               | Persist and compare trust snapshots over time         |
-| `mjolnir evidence-graph`            | Build or query the verification evidence graph        |
-| `mjolnir rules --unmeasured`        | The rules running on assumption, not measurement      |
-| `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 and its fixtures                  |
-| `mjolnir stats`                     | Local all-time counters of fixes seen                 |
-| `mjolnir badge`                     | shields.io endpoint JSON and snippet                  |
-| `mjolnir --cache`                   | Incremental re-scans via a local verdict cache        |
-| `mjolnir --format mermaid`          | Test-architecture diagram for a PR comment            |
+Static analysis reasons about code that never ran. The evidence path reads
+what actually happened: Playwright JSON, Jest JSON, Vitest JSON, and JUnit
+XML from any runner. The `forensics` and `triage` verbs are retired in the
+v6 carve; this capability arrives as `mjolnir explain --evidence <dir>` with
+the next slice.
-`mjolnir help <command>` prints usage, examples and the next step for any
-of them.
-</details>
-Requires **Node.js ≥ 22.18** on Windows, macOS or Linux. Prefer a global
-install? `npm i -g mjolnir-qa`. The floor comes from the build toolchain
-(tsdown targets it and the release pipeline smoke-tests against it); the
-runtime dependencies need no more than that.
+```text
+  ▍ FLAKINESS LEADERBOARD
-<br />
+3 tests · 1 failed · 1 flaky · 1 retried
-## What Mjölnir finds
+TRUE-FLAKE completes checkout with saved card (e2e/checkout.spec.ts)
+           ████████████████████ 6.0s · 2 attempts
+FAILING    declines an expired card (e2e/checkout.spec.ts)
+           ████░░░░░░░░░░░░░░░░ 1.1s · 1 attempt
+```
-<p align="center">
-  <img src="assets/readme/stack.svg" alt="Works with your stack: the languages, test frameworks and CI systems its rules cover, from the rule registry." width="100%" />
-</p>
+`TRUE-FLAKE` does not mean the test retried. It means the test **failed at
+least one attempt and then finished green**: a lucky pass, flagged whatever
+the final checkmark says. The evidence path turns that history into a
+quarantine proposal, and `mjolnir explain --playwright` summarizes a run. The same run
+reports are what lift findings to trust levels L3 and above.
-**<!-- census:total-rules -->79 rules<!-- /census:total-rules -->** in four families — test hygiene, test quality, Playwright and
-CI integrity — across TypeScript and JavaScript, Python, Java, C# and
-GitHub Actions YAML. They cover Playwright in all four bindings, plus
-pytest, JUnit, TestNG, NUnit, xUnit, MSTest, Jest, Vitest and Mocha, with
-starter coverage for Cypress and Selenium. Nine of them, to show the shape:
-| ID           | Rule                                                              | Severity | Tier       |
-| ------------ | ----------------------------------------------------------------- | -------- | ---------- |
-| QA-CI-001    | `continue-on-error` masks a failing verification gate             | error    | quarantine |
-| QA-CI-009    | Test exit code not propagated (`\|` without pipefail, `;` chains) | error    | extended   |
-| QA-TEST-001  | Focused test committed (`.only`, `fit`)                           | error    | quarantine |
-| QA-TEST-003  | Test with no assertions                                           | error    | quarantine |
-| QA-TQUAL-009 | Unawaited promise assertion                                       | error    | quarantine |
-| QA-PW-002    | Unawaited locator assertion                                       | error    | core       |
-| QA-PW-004    | Brittle CSS/XPath selectors                                       | warning  | quarantine |
-| QA-PY-002    | Skipped test (`skip`, non-strict `xfail`)                         | warning  | core       |
-| QA-CS-103    | Test method with no assertions                                    | error    | core       |
-The full catalog is generated from the registry, never maintained by hand:
-`mjolnir rules --md`, [`docs/rules/`](docs/rules/), or the
-[what-it-checks guide](https://sergey-bar.github.io/Mjolnir/guide/what-it-checks).
+</details>
 <details>
-<summary><strong>Every rule named in this README</strong>, in one table</summary>
+<summary><strong>Selector Health Score</strong> — <code>mjolnir doctor --frameworks</code></summary>
 <br />
-> `quarantine` rules run only under `--strict` and never gate (they are
-> capped to info). The severity shown is the authored severity.
-| ID           | Family     | Rule                                                         | Severity | Tier       |
-| ------------ | ---------- | ------------------------------------------------------------ | -------- | ---------- |
-| QA-TEST-001  | Hygiene    | Focused test committed (`.only`, `fit`)                      | error    | quarantine |
-| QA-TEST-002  | Hygiene    | Skipped test. Escalates to `error` without a tracked reason. | warning  | quarantine |
-| QA-TEST-003  | Hygiene    | Test with no assertions                                      | error    | quarantine |
-| QA-TEST-004  | Hygiene    | Hard sleep (`waitForTimeout`, `sleep()`, `delay()`)          | warning  | extended   |
-| QA-TEST-006  | Hygiene    | Retry abuse hiding flakiness                                 | warning  | quarantine |
-| QA-TEST-010  | Hygiene    | Empty test body                                              | error    | quarantine |
-| QA-TQUAL-002 | Quality    | Tautological assertion                                       | error    | quarantine |
-| QA-TQUAL-009 | Quality    | Unawaited promise assertion                                  | error    | quarantine |
-| QA-TQUAL-011 | Quality    | Commented-out tests                                          | warning  | extended   |
-| QA-PW-002    | Playwright | Unawaited locator assertion                                  | error    | core       |
-| QA-PW-003    | Playwright | `page.pause()` / `test.only()` committed                     | error    | core       |
-| QA-PW-004    | Playwright | Brittle CSS/XPath selectors                                  | warning  | quarantine |
-| QA-PW-123    | Playwright | Hardcoded environment URLs                                   | warning  | quarantine |
-| QA-PW-140    | Playwright | Screenshot without `maxDiffPixelRatio`                       | warning  | core       |
-| QA-CI-001    | CI         | `continue-on-error` masks a failing gate                     | error    | quarantine |
-| QA-CI-002    | CI         | `\|\| true` swallows exit codes                              | error    | extended   |
-| QA-CI-005    | CI         | Report consumed but never generated                          | error    | quarantine |
-| QA-CI-007    | CI         | Retry wrappers around tests                                  | warning  | extended   |
-| QA-CI-008    | CI         | Always-success step masks failures                           | error    | quarantine |
-| QA-CI-009    | CI         | Exit code not propagated (`\|` without pipefail, `;` chains) | error    | extended   |
-| QA-CI-010    | CI         | Tests skipped where they must block                          | error    | quarantine |
-| QA-PY-002    | Python     | Skipped test (`skip`, non-strict `xfail`)                    | warning  | core       |
-| QA-PY-003    | Python     | Test function with no assertions                             | error    | quarantine |
-| QA-PY-005    | Python     | `time.sleep()` in tests                                      | warning  | extended   |
-| QA-PY-012    | Python     | Tautological assertion                                       | error    | quarantine |
-| QA-JV-101    | Java       | Disabled test (`@Disabled`)                                  | warning  | core       |
-| QA-JV-102    | Java       | Hard sleep (`Thread.sleep()`)                                | warning  | extended   |
-| QA-JV-103    | Java       | Test method with no assertions                               | error    | extended   |
-| QA-JV-105    | Java       | Playwright `waitForTimeout()` hard sleep                     | warning  | core       |
-| QA-JV-106    | Java       | Brittle selector instead of role locator                     | warning  | quarantine |
-| QA-CS-101    | C#         | Skipped test (`[Ignore]`, `[Fact(Skip=)]`)                   | warning  | core       |
-| QA-CS-102    | C#         | Hard sleep (`Thread.Sleep` / `Task.Delay`)                   | warning  | core       |
-| QA-CS-103    | C#         | Test method with no assertions                               | error    | core       |
-| QA-CS-105    | C#         | `WaitForTimeoutAsync()` hard sleep                           | warning  | extended   |
-| QA-CS-106    | C#         | Brittle selector instead of role locator                     | warning  | quarantine |
-Python also ships QA-PY-001…012 (pytest hygiene) and QA-PY-101…108
-(Playwright for Python). Cypress and Selenium have starter sets of three
-rules each.
-</details>
-Every rule ships with a must-fire **and** a must-not-fire fixture, and a
-rule that fires on its own negative fixture cannot ship. That is the
-false-positive firewall; `mjolnir doctor` enforces it in this repository's
-own CI.
-### Selector Health Score
-`mjolnir doctor:playwright` grades every locator by how it finds an
+`mjolnir doctor --frameworks` grades every locator by how it finds an
 element: the way a user would (role, label, text), an explicit contract
 (`data-testid`), or a structural accident (CSS chains, XPath). Each file
 gets a score from 0 to 100:
@@ -424,430 +363,97 @@ This measures **resilience, not correctness**.
 someone touches the markup. A low score never claims the test is broken,
 only that it depends on markup nobody promised to keep.
-<br />
-## The Worthiness Score
-<p align="center">
-  <img src="assets/readme/score-gauge.svg" alt="The worthiness scale from 0 to 100, with a marker sweeping every score: UNWORTHY below 50, NEEDS WORK from 50 to 79, WORTHY from 80 to 99, FORGED at 100" width="720" />
-</p>
-<sub>Every score from 0 to 100, placed by the real `deriveScoreState`.
-Generated by `npm run docs:gauge` and drift-locked in CI.</sub>
-| Score     | Verdict                                 |
-| --------- | --------------------------------------- |
-| `0 – 49`  | **UNWORTHY**                            |
-| `50 – 79` | **NEEDS WORK**                          |
-| `80 – 99` | **WORTHY**                              |
-| `100`     | **FORGED**                              |
-| `null`    | **UNKNOWN**: no test declarations found |
-**How it is computed.** Severity sets a base deduction (`error −8`,
-`warning −3`, `info −1`) and the evidence level discounts it: E2 pays in
-full, E1 half (rounded down), E0 nothing. The total is normalized by suite
-exposure, meaning deductions per test declaration rather than per file.
-The terminal prints the same discounted numbers the score used; there is
-no hidden second model. Details: [docs/SCORING.md](docs/SCORING.md) and the
-[scoring guide](https://sergey-bar.github.io/Mjolnir/guide/scoring).
-**What 100 does not mean.** It does not mean the software is correct, the
-suite is adequate, or the product is free of defects. It means one thing:
-**none of Mjölnir's evaluated rules produced a deduction under this scan
-and this evidence model.**
-<br />
-## The evidence model
-Every finding carries two labels: how sure Mjölnir is, and how far the
-finding was checked. That is the difference between a tool that reports
-patterns and a tool you can gate a release on.
-**How sure — the evidence level.**
-| Level  | Name                | Means                                              | Deduction |
-| ------ | ------------------- | -------------------------------------------------- | --------- |
-| **E2** | Deterministic proof | The defect is present in the code as written       | Full      |
-| **E1** | Pattern evidence    | A pattern strongly tied to the defect matched      | Half      |
-| **E0** | Observation         | Worth knowing. Not a claim that anything is wrong. | Zero      |
-Confidence in a detection is not the strength of the proof. A rule can be
-certain it matched what it looked for and still be looking at a heuristic.
-E1 findings are there to be read and judged, never applied blindly, and
-that boundary is stamped on the finding in the terminal, the JSON and the
-agent handoff.
-**How far it was checked — the trust level.** Most findings come from
-reading your code. Give Mjölnir the report of a real test run and it can
-confirm that the code actually ran.
-<p align="center">
-  <img src="assets/readme/trust-ladder.svg" alt="The trust ladder from L0 to L5. L0 to L2 come from reading the code; L3 to L5 need a real run report, marked by a break in the ladder." width="100%" />
-</p>
-| Level  | In plain words         | What it takes                                  |
-| ------ | ---------------------- | ---------------------------------------------- |
-| **L0** | Noted                  | Reading the code                               |
-| **L1** | Looks like the problem | Reading the code: a pattern matched            |
-| **L2** | Proven in the code     | Reading the code: the defect is structural     |
-| **L3** | The file ran           | A run report shows the finding's file executed |
-| **L4** | The test ran           | A run report shows the finding's test executed |
-| **L5** | The run agrees         | The run's own result confirms the defect class |
-A static scan stops at L2. Only a real run report (Playwright JSON, Jest or
-Vitest JSON, JUnit XML) can lift a finding to L3 or above, so a finding
-that was never seen running can never claim it was. Definitions:
-[docs/TERMINOLOGY.md](docs/TERMINOLOGY.md).
-### How much of this is measured
-**<!-- census:measured-of-total -->74 of 79<!-- /census:measured-of-total --> rules carry a false-positive rate measured against real OSS code**
-(at least 10 hand-classified findings each; see
-[docs/FP-AUDIT.md](docs/FP-AUDIT.md)). The other <!-- census:unmeasured -->5<!-- /census:unmeasured --> ship on the author's estimate and say so, rule by rule,
-in `mjolnir explain`. `mjolnir rules --unmeasured` lists them, and every
-scan footer reports how many of the rules that actually _fired_ are
-measured.
-Rates stay public when they are bad. QA-TEST-001 (a committed `.only`)
-audits poorly on real repositories and sits in quarantine for it. The live
-number for every rule, QA-PW-141 included, is in the audit.
-### Trust tiers
-Tiers follow the measured false-positive rate, not opinion:
-| Tier           | Measured FP                  | Behavior                                     |
-| -------------- | ---------------------------- | -------------------------------------------- |
-| **core**       | ≤ 10%                        | Default report, gates                        |
-| **extended**   | ≤ 30%                        | Default report, lower confidence             |
-| **quarantine** | > 30% or explicitly declared | `--strict` only, capped to info, never gates |
-| _unmeasured_   | n < 10                       | Cannot be promoted to core until measured    |
-FP bands can only demote a tier — they never promote a rule out of
-`quarantine` if it was explicitly declared there. An explicitly
-quarantined rule stays quarantine regardless of its measured FP rate.
-Promotion, demotion and per-language maturity:
-[rule lifecycle](https://sergey-bar.github.io/Mjolnir/reference/rule-lifecycle).
-### Why this is not a linter
-Linters tell you whether code follows rules. Mjölnir tells you whether your
-verification can be trusted.
-|                                                                      | Linters (ESLint, SonarQube) | Coverage tools | AI code review |   **Mjölnir**    |
-| -------------------------------------------------------------------- | :-------------------------: | :------------: | :------------: | :--------------: |
-| Scores the **verification system**, not the product code             |             No              |       No       |       No       |       Yes        |
-| CI workflow integrity (`continue-on-error`, `\|\| true`)             |             No              |       No       | only the diff  |       Yes        |
-| Grades Playwright locator resilience (Selector Health)               |             No              |       No       |       No       |       Yes        |
-| Reads real run data for `TRUE-FLAKE` verdicts                        |             No              |       No       |       No       |       Yes        |
-| Publishes measured false-positive rates where corpus evidence exists |             No              |       No       |       No       |       Yes        |
-| Flags tests with no assertions                                       |            Yes\*            |       No       |   sometimes    |       Yes        |
-| Catches hard sleeps (`waitForTimeout`, `time.sleep`)                 |            Yes\*            |       No       |   sometimes    |       Yes        |
-| Deterministic (same input, same output)                              |             Yes             |      Yes       |       No       |       Yes        |
-| Cost per scan                                                        |            free             |      free      |     tokens     | **zero** (local) |
-<sub>\*Covered by `eslint-plugin-jest` and `eslint-plugin-playwright`
-(`expect-expect`, `no-wait-for-timeout`) and by SonarQube's own assertion
-rules. The columns describe default behavior for test-suite verification;
-plugins, paid tiers and custom rules change some answers. This is a
-positioning summary, not a benchmark.</sub>
-Use AI review too. It catches nuance, intent and design flaws no pattern
-can find. Mjölnir catches what AI review overlooks because it looks
-intentional: a committed `.only`, a swallowed exit code, a
-`continue-on-error` on a test job. Those need scanning, not reasoning.
-<br />
-## Runtime forensics
-Static analysis reasons about code that never ran. Forensics reads what
-actually happened: Playwright JSON, Jest JSON, Vitest JSON, and JUnit XML
-from any runner.
-```bash
-mjolnir forensics ./test-results/
-```
-```text
-  ▍ FLAKINESS LEADERBOARD
-3 tests · 1 failed · 1 flaky · 1 retried
-TRUE-FLAKE completes checkout with saved card (e2e/checkout.spec.ts)
-           ████████████████████ 6.0s · 2 attempts
-FAILING    declines an expired card (e2e/checkout.spec.ts)
-           ████░░░░░░░░░░░░░░░░ 1.1s · 1 attempt
-```
-`TRUE-FLAKE` does not mean the test retried. It means the test **failed at
-least one attempt and then finished green**: a lucky pass, flagged whatever
-the final checkmark says. `mjolnir triage` turns that history into a
-quarantine proposal, and `mjolnir pw-report` summarizes a run. The same run
-reports are what lift findings to trust levels L3 and above.
-<br />
-## CI integrity
-A test can pass while the pipeline around it cannot fail. Mjölnir reads the
-workflows too: `continue-on-error`, `|| true`, exit codes that never
-propagate, always-success steps, reports consumed but never generated, and
-gates skipped on the events that should block. Each finding names the job,
-the step and the line, and carries its own evidence level.
-Generate an advisory PR workflow first. It reports findings without blocking
-and is pinned to this version, so adopting it cannot change gate semantics:
-```bash
-mjolnir ci install
-```
-The generated workflow is advisory by default. A direct
-`uses: Sergey-Bar/Mjolnir@...` composite Action is blocking by default; set
-`fail-on` explicitly when its policy differs.
-After reviewing existing debt, opt into an enforcing gate:
-```bash
-mjolnir ci install --gate error
-```
-In your existing workflow, pin the action and explicitly opt into an error gate:
-```yaml
-- uses: Sergey-Bar/Mjolnir@4a588bc62d517bc85fc44c0eae64c6587d3bf70b0
-  with:
-    scope: changed
-    fail-on: error
-```
-The `--blocking error` flag does the same in any CI pipeline:
-```bash
-npx mjolnir-qa@5.0.0 --scope changed --blocking error
-```
-To put findings in GitHub Code Scanning, upload SARIF (requires
-`security-events: write` at workflow or job scope):
-```yaml
-- run: npx mjolnir-qa@5.0.0 --format sarif > mjolnir.sarif
-  continue-on-error: true
-- uses: github/codeql-action/upload-sarif@v3
-  if: ${{ !cancelled() }}
-  with:
-    sarif_file: mjolnir.sarif
-```
+</details>
-On GitLab, `--format codequality` writes the Code Quality report that the
-MR widget and diff annotations read ([docs/GITLAB-CI.md](docs/GITLAB-CI.md)).
-Editor and pipeline setup: [docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md).
+---
-### Changed-scope attribution
+## AI agents: SCAN → EVIDENCE → HANDOFF → AGENT → RE-SCAN → PROOF
 ```bash
-npx mjolnir-qa@5.0.0 --scope changed
-```
-Findings are attributed to the lines your branch added, measured against
-the **merge-base**. The scope is the same file set a full scan discovers
-(TS/JS specs and adapter configs, `test_*.py`, `*Test.java`, `*Tests.cs`,
-`.github/workflows/*.yml`), plus uncommitted and untracked changes, so it
-works before you commit. The base resolves
-`main → master → origin/main → origin/master → origin/HEAD`; override it
-with `--base <ref>`.
-When the merge-base cannot be resolved (a shallow clone, a detached HEAD, a
-target outside git), findings fall back to whole-file attribution **and the
-report says so.** A silent fallback would be the same kind of defect this
-tool exists to catch.
-<br />
-## AI agents
+# MCP server over stdio (read-only tools: scan, explain, diff, verify, forensics, triage, pw-report)
+claude mcp add mjolnir -- npx -y mjolnir-qa@latest mcp
-Findings are only worth something if something acts on them.
+# Deterministic handoff plan for any agent
+mjolnir handoff
-```text
-SCAN → EVIDENCE → HANDOFF → AGENT → RE-SCAN → PROOF
+# Install into your repo's agent surfaces (.claude/, .cursor/, .kilo/, AGENTS.md)
+mjolnir install
 ```
-**AI writes the fix. Mjölnir verifies it.** The proof comes from the
-re-scan, never from the agent's own report of success.
+Every finding in a handoff carries its boundary: **E2** = deterministic, apply fix; **E1** = requires confirmation, do not suppress blindly.
-| Command           | What the agent gets                                                                                                                                                    |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mjolnir mcp`     | An [MCP](https://modelcontextprotocol.io) server over stdio. `scan`, `explain`, `diff`, `verify`, `forensics`, `triage`, and `pw-report` are read-only callable tools. |
-| `mjolnir handoff` | A saved `--json` report becomes a deterministic Markdown plan: what was detected, the evidence boundary per finding, what must **not** change, how to verify.          |
-| `mjolnir install` | Writes into the agent surfaces your repo already has (`.claude/`, `.cursor/`, `.kilo/`, `AGENTS.md`) so the agent re-scans before it claims it is done.                |
+---
-Add it to a client that ships its own CLI:
+## Trust and security
-```bash
-claude mcp add mjolnir -- npx -y mjolnir-qa@5.0.0 mcp
-```
+- **Local-first, zero telemetry.** No network-capable API exists in `src/`. A contract test (`privacy-network-isolation.spec.ts`) fails the build if one appears. Scanning untrusted code never executes it.
+- **Plugins are not sandboxed** — same trust model as ESLint/Vitest plugins. Opt-in per scan with `--enable-plugins`.
+- **Self-verifying.** Every CI run scans this repository with the build it produced. The gate fails on any error finding, a partial scan, or a crashed rule. `mjolnir doctor` re-audits the rule base in the same run.
-Or to any client that takes an `mcpServers` block:
-```json
-{
-  "mcpServers": {
-    "mjolnir": {
-      "command": "npx",
-      "args": ["-y", "mjolnir-qa@5.0.0", "mcp"]
-    }
-  }
-}
-```
+---
-**The guardrail matters more than the convenience.** Every finding in a
-handoff carries its 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 blindly, suppresses
-a rule, or edits a rule to raise the score is doing exactly what this tool
-exists to catch, so the handoff says so in the prompt, next to the finding.
+## Exit codes (frozen contract)
-<br />
+| Code | Meaning                                                                          |
+| ---- | -------------------------------------------------------------------------------- |
+| `0`  | Clean — no findings at or above the gate                                         |
+| `1`  | Findings at or above the gate                                                    |
+| `2`  | Inconclusive — partial scan, unreadable files, or crashed rule. A CI step fails. |
+| `10` | Usage error                                                                      |
+| `20` | Internal error                                                                   |
-## Trust and security
-**Local-first, zero telemetry.** No network-capable API (`fetch`, `http`,
-`https`, `net`, `dns`, `dgram`, WebSocket) exists anywhere in `src/`, and
-[`privacy-network-isolation.spec.ts`](tests/contract/privacy-network-isolation.spec.ts)
-fails the build if one appears. It also bars `eval` and `new Function`.
-Scanning untrusted code never executes it: static analysis reads source
-text, and forensics parses report files that already exist on disk.
-Two caveats: `npx` itself fetches the package before anything runs, and the
-guarantee covers `src/`, not third-party plugins.
-**Plugins are not sandboxed.** JS plugins (`mjolnir-rules/*.mjs`, or npm
-packages listed under `"plugins"`) run with full Node privileges, the same
-trust model as ESLint or Vitest plugins. Loading them is opt-in **per
-scan**: without `--enable-plugins` (or `MJOLNIR_ENABLE_PLUGINS=1`) their
-sources are never loaded, and a notice on stderr lists what was skipped.
-JSON rule manifests execute no code, and core rule-ID prefixes are reserved
-so a plugin cannot impersonate one. Report vulnerabilities through
-[SECURITY.md](SECURITY.md).
-**It runs on itself.** A verification trust engine has no standing unless
-it is itself verifiable. Every CI run scans this repository with the build
-that same run produced. The gate fails on any error-severity finding, and
-also on a **partial** scan or a **crashed rule**, because a truncated
-self-scan that reports nothing is the false green this project exists to
-catch. `mjolnir doctor` re-audits the rule base in the same run (fixture
-firewall, tier honesty, the core-tier cap), and an INCONCLUSIVE check fails
-exactly like a failing one. Both reports are uploaded as build artifacts.
-### Exit codes and the machine contract
-Frozen, so you can build CI logic on them:
-| 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                                                  |
-`2` is deliberately distinct from `0`: a scan that did not finish has not
-found nothing. It has not finished looking.
-Everything a machine consumes (MCP tool results, `--json`, SARIF 2.1) comes
-from one canonical result under a versioned, **additive-only** schema
-(`schemaVersion: 1`, `contractVersion: 1`), so no consumer has to rebuild
-meaning from rendered text. See [the machine contract](docs/machine-contract.md).
-Rule IDs (`QA-<FAMILY>-NNN`) are immutable once shipped and never reused.
+`2` is distinct from `0`: an incomplete scan has not found nothing — it has not finished looking. No flag turns it into `0`. [`docs/VERSIONING.md`](docs/VERSIONING.md) is the law.
-<br />
+---
 ## What Mjölnir cannot tell you
-- **It does not run your tests.** A clean scan is not a passing suite.
-- **It cannot tell you an assertion is _wrong_.** `expect(total).toBe(41)`
-  looks healthy. Mjölnir finds tests that _cannot fail_ and pipelines that
-  _cannot go red_, not tests that check the wrong thing.
-- **It does not prove business correctness.** Nothing here says your
-  product does what the requirement asked for.
-- **A 100 is not proof of a good suite.** Whether your suite covers your
-  real risk is a different question, and this tool does not answer it.
-- **<!-- census:unmeasured-of-total -->5 of 79<!-- /census:unmeasured-of-total --> rules ship on an estimate**, not a measured rate. Each one
-  says so on its own finding.
-- **E1 is not E2.** Heuristic findings are worth reading, not worth applying
-  blindly.
-- **An empty repo scores `null`, never 100.**
-- **A file named `*.spec.ts` with no test declarations does not count as coverage.** A repo whose only spec files contain imports or types (zero `it`/`test` calls) scores `null`, not 100.
+- It does not run your tests. A clean scan ≠ a passing suite.
+- It cannot tell you an assertion is **wrong** — only that it **cannot fail**.
+- It does not prove business correctness.
+- A score of 100 means: _none of Mjölnir's evaluated rules produced a deduction under this scan and evidence model._
+- <!-- census:unmeasured-of-total -->6 of 79<!-- /census:unmeasured-of-total --> rules ship on an estimate, not a measured FP rate. Each says so on its finding.
+- E1 is not E2 — heuristic findings are worth reading, not worth applying blindly.
-<br />
+---
 ## Documentation
-The full docs site is at <https://sergey-bar.github.io/Mjolnir/>.
-| Document                                                           | What's in it                                              |
-| ------------------------------------------------------------------ | --------------------------------------------------------- |
-| [docs/EXECUTIVE-ROI.md](docs/EXECUTIVE-ROI.md)                     | Business case for decision-makers                         |
-| [docs/SCORING.md](docs/SCORING.md)                                 | Score normalization and evidence weighting                |
-| [docs/TERMINOLOGY.md](docs/TERMINOLOGY.md)                         | Canonical vocabulary: one word per concept                |
-| [docs/FP-AUDIT.md](docs/FP-AUDIT.md)                               | Measured false-positive rates and the method              |
-| [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md)                   | Rule states, tiers, suppression, deprecation              |
-| [docs/VERSIONING.md](docs/VERSIONING.md)                           | Semver policy, frozen surfaces, deprecation cycle         |
-| [docs/machine-contract.md](docs/machine-contract.md)               | The canonical machine-readable result                     |
-| [docs/SARIF-INTEGRATION.md](docs/SARIF-INTEGRATION.md)             | SARIF output and editor or CI setup                       |
-| [docs/GITLAB-CI.md](docs/GITLAB-CI.md)                             | GitLab: Code Quality report, MR recipe, gate              |
-| [docs/rules/](docs/rules/)                                         | Generated per-rule catalog                                |
-| [CONTRIBUTING.md](CONTRIBUTING.md)                                 | Dev setup and contribution workflow                       |
-| [SUPPORT.md](SUPPORT.md)                                           | Where to ask, report and get help                         |
-| [SECURITY.md](SECURITY.md)                                         | Vulnerability reporting                                   |
-| [docs/MIGRATION-3.0.0.md](docs/MIGRATION-3.0.0.md)                 | 3.0.0 migration checklist                                 |
-| [docs/INSTALLATION-3.0.0.md](docs/INSTALLATION-3.0.0.md)           | Reproducible CLI, Action, and MCP installation            |
-| [docs/ROLLBACK-3.0.0.md](docs/ROLLBACK-3.0.0.md)                   | Rollback and corrective-release procedure                 |
-| [docs/RELEASE-3.0.0-READINESS.md](docs/RELEASE-3.0.0-READINESS.md) | 3.0.0 release gates, migration, QA, and rollout checklist |
-| [CHANGELOG.md](CHANGELOG.md)                                       | Release history                                           |
+| Document                                                     | What's in it                                            |
+| ------------------------------------------------------------ | ------------------------------------------------------- |
+| [docs/VERSIONING.md](docs/VERSIONING.md)                     | Semver policy, frozen surfaces, deprecation cycle       |
+| [docs/machine-contract.md](docs/machine-contract.md)         | The canonical machine-readable result                   |
+| [docs/MIGRATION-CONTRACT-2.md](docs/MIGRATION-CONTRACT-2.md) | Machine-contract v2: `coverageState` and degraded scans |
+| [docs/FP-AUDIT.md](docs/FP-AUDIT.md)                         | Measured false-positive rates and the method            |
+| [CONTRIBUTING.md](CONTRIBUTING.md)                           | Dev setup and contribution workflow                     |
+| [SUPPORT.md](SUPPORT.md)                                     | Where to ask, report and get help                       |
+| [SECURITY.md](SECURITY.md)                                   | Vulnerability reporting                                 |
 ### Status
-**Version 3.0.0.** The JSON schema and the exit codes are frozen contracts.
-TypeScript and Python have the broadest measured coverage. Java and C# are
-newer; read them through the
-[maturity table](https://sergey-bar.github.io/Mjolnir/reference/rule-lifecycle).
-What comes next, with no invented dates:
+**Version 6.0.1 published.** The JSON schema and the exit codes are frozen contracts. What comes next, with 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 the
-rule with its must-fire **and** must-not-fire fixtures. The generated rule
-fails its own fixtures on purpose until real detection is written, because
-a stub that ships is a rule nobody measured:
-```bash
-mjolnir create-rule QA-PW-140 --title "Screenshot without diff bound"
-```
-Dev setup, the standing-gate commands, and the anti-creep and
-fixture-firewall laws are in [CONTRIBUTING.md](CONTRIBUTING.md).
+---
-<br />
+<p align="center">
+  <img src="assets/readme/how-it-works.svg" alt="How Mjölnir works" width="880" />
+</p>
 <div align="center">
 <img src="assets/readme/closing.svg" alt="Run it on your repo." width="100%" />
 ```bash
-npx mjolnir-qa@5.0.0
+npx mjolnir-qa@latest
 ```
-[Read the guide](https://sergey-bar.github.io/Mjolnir/guide/getting-started) · [Docs site](https://sergey-bar.github.io/Mjolnir/) · [npm](https://www.npmjs.com/package/mjolnir-qa)
+[Read the guide](https://sergey-bar.github.io/Mjolnir/guide/getting-started) · [Docs](https://sergey-bar.github.io/Mjolnir/) · [npm](https://www.npmjs.com/package/mjolnir-qa)
 <br />
-Don't ask whether the tests passed.<br />
-Ask whether the evidence proves they deserve to be trusted.
+**Don't ask whether the tests passed.**
+**Ask whether the evidence proves they deserve to be trusted.**
 <sub>Built by [Sergey Bar](https://www.linkedin.com/in/sergeybar/) · MIT licensed</sub>