npm - mjolnir-qa - Versions diffs - 4.0.0 → 6.0.0 - Mend

mjolnir-qa 4.0.0 → 6.0.0

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

package/CHANGELOG.md +3178 -16
package/README.md +81 -760
package/dist/cli.d.mts +552 -206
package/dist/cli.mjs +31409 -13990
package/dist/mcp/stdio.mjs +1290 -405
package/package.json +76 -32
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/scan-pipeline-Bg-46cLS.mjs +0 -2
package/dist/scan-pipeline-CCJdEKNa.mjs +0 -16336

package/README.md CHANGED Viewed

@@ -1,470 +1,99 @@
 <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 />
 [![npm](https://img.shields.io/npm/v/mjolnir-qa.svg?style=flat-square&color=1F6F7C&labelColor=0A1119)](https://www.npmjs.com/package/mjolnir-qa)
-[![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@4.0.0
+npx mjolnir-qa@6.0.0
 ```
-[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)
-<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>
+[**Interactive walkthrough**](https://sergey-bar.github.io/Mjolnir/) · [Docs](https://sergey-bar.github.io/Mjolnir/) · [CHANGELOG](CHANGELOG.md) · [Video](assets/video/mjolnir-demo.mp4)
 </div>
-<br />
-## 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:
-- 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
-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.**
-Here is Mjölnir reading a real one:
-<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" />
-</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@4.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:
-| 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.         |
-<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" />
-</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>
-<br />
-## Release status
-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.
-## 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:
-<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" />
-</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>
-<details>
-<summary><strong>Watch it</strong> — a scan, the fix it prints, and the re-scan that proves it</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@4.0.0 scanning the demo repository in a terminal window" width="900" />
-  </a>
-</p>
+## The problem: a green check is a claim, not proof
-<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>
+A green check means the pipeline did not fail. It does **not** mean the tests ran, or that they could have failed.
-</details>
-### One finding, up close
+```yaml
+# These all ship green. None earned it.
+steps:
+  - run: npm test || true # exit code swallowed
+  - run: pytest tests/ --maxfail=0 # retry wrapper
+  - run: playwright test --workers=1 # serial but no --exit-on-failure
+  - uses: some/action@main # mutable ref
+```
-Every finding answers four questions: where it is, how sure Mjölnir is,
-how often the rule is wrong, and how to fix it.
+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/finding-anatomy.svg" alt="The first finding of the demo scan, exactly as the terminal prints it, with its four parts marked: where, how sure, how often the rule is wrong, and the fix." width="100%" />
+  <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>
-`mjolnir explain QA-CI-001` prints a rule's whole trust record, including
-its measured false-positive rate and the tier that rate earned it:
-```text
-  ▍ QA-CI-001 — continue-on-error masks a failing verification gate
-Severity:    error
-Confidence:  high
-Tier:        quarantine
-Evidence:    E2
-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, azure-pipelines
-COPY-READY REVIEW COMMENT
-  Advisory finding — this does not block merging: Job `security-scan` runs a
-  verification gate under `continue-on-error: true`.
-  Why it weakens verification: This job can fail every day and CI will still
-  show green. The checkmark on this workflow cannot be trusted.
-  Confidence: high, evidence E2, tier quarantine; measured FP 11% (19 verdicts).
-  Suggested fix: Remove continue-on-error, or scope it to individual
-  non-blocking steps only.
-  Verify with: mjolnir --scope changed, then mjolnir explain QA-CI-001 if the
-  finding still appears.
-WHAT WAS FOUND (real detector output, not a mockup)
-  Job `security-scan` runs a verification gate under `continue-on-error: true`.
-WHY IT MATTERS
-  This job can fail every day and CI will still show green. The checkmark on
-  this workflow cannot be trusted.
-HOW TO FIX
-  Remove continue-on-error, or scope it to individual non-blocking steps only.
-  Example from this rule's own must-fire fixture: QA-CI-001/must-fire/masked.yml
-WHAT WOULD CHANGE THE VERDICT
-  - a run report next to the scan target (mjolnir.report.json or test-results/)
-  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
-NEXT ACTION
-  Fix the first occurrence, then re-run: `mjolnir --scope changed`. Every
-  occurrence of this rule is listed in the scan output.
-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: one place where CI reports a pass it did not earn.
-<br />
+---
 ## Quickstart
 ```bash
-npx mjolnir-qa@4.0.0
-```
+# 1. Scan — Trust Report, exits 1 on gate findings
+npx mjolnir-qa@6.0.0
-Three steps to trust your release pipeline:
+# 2. Block in CI — scan only what your branch changed
+npx mjolnir-qa@6.0.0 --scope changed
-1. **Scan** — `npx mjolnir-qa@4.0.0` — scans the current directory, prints the Trust Report, exits `1` if findings at the gate
-2. **Block in CI** — `npx mjolnir-qa@4.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
+# 3. Fix and re-verify — safe auto-fixes, each re-scanned to prove it landed
+mjolnir fix
 ```
-After reviewing the findings or baselining existing debt, opt into blocking:
+**Prove the fix with a baseline, then delta:**
 ```bash
-mjolnir ci install --gate error
+npx mjolnir-qa@6.0.0 --save-baseline   # once: writes .mjolnir/baseline.json
+# … make the fix …
+mjolnir ci verify                 # RESOLVED (gone) / NEW (introduced)
 ```
-| 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>
-<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 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            |
-`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.
-<br />
-## What Mjölnir finds
-<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>
+---
-**<!-- 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>
-<summary><strong>Every rule named in this README</strong>, in one table</summary>
+## What it catches by default (79 rules)
-<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
-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:
-```text
-  ▍ SELECTOR HEALTH
-e2e/login.spec.ts
-  [█████████████░░░░░░░]  65 / 100
-  role/text: 1 · testid: 0 · plain-css: 0 · css-chains: 1 ⚠ · xpath: 0
-e2e/checkout.spec.ts
-  [██████████████████░░]  88 / 100
-  role/text: 4 · testid: 1 · plain-css: 0 · css-chains: 1 ⚠ · xpath: 0
-```
+| Family           | Example rules                                                                                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **CI integrity** | `                                                                                                                   |     | true` swallowing exit codes (`QA-CI-002`), `continue-on-error` on gate jobs (`QA-CI-001`), mutable Action refs (`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                                                       |
-This measures **resilience, not correctness**.
-`.btn.btn-primary > div:nth-child(2)` passes today and keeps passing until
-someone touches the markup. A low score never claims the test is broken,
-only that it depends on markup nobody promised to keep.
+Full catalog: `mjolnir explain --list --md` or [what-it-checks](https://sergey-bar.github.io/Mjolnir/guide/what-it-checks). **73 of 79 rules carry a measured false-positive rate.**
-<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" />
+  <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>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.**
+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.
-<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.**
+## Evidence you can gate on
 | Level  | Name                | Means                                              | Deduction |
 | ------ | ------------------- | -------------------------------------------------- | --------- |
@@ -472,382 +101,74 @@ patterns and a tool you can gate a release on.
 | **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.
+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).
-**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:
+## AI agents: SCAN → EVIDENCE → HANDOFF → AGENT → RE-SCAN → PROOF
 ```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
-```
+# MCP server over stdio (read-only tools: scan, explain, diff, verify, forensics, triage, pw-report)
+claude mcp add mjolnir -- npx -y mjolnir-qa mcp
-The `--blocking error` flag does the same in any CI pipeline:
+# Deterministic handoff plan for any agent
+mjolnir handoff
-```bash
-npx mjolnir-qa@4.0.0 --scope changed --blocking error
+# Install into your repo's agent surfaces (.claude/, .cursor/, .kilo/, AGENTS.md)
+mjolnir install
 ```
-To put findings in GitHub Code Scanning, upload SARIF (requires
-`security-events: write` at workflow or job scope):
+Every finding in a handoff carries its boundary: **E2** = deterministic, apply fix; **E1** = requires confirmation, do not suppress blindly.
-```yaml
-- run: npx mjolnir-qa@4.0.0 --format sarif > mjolnir.sarif
-  continue-on-error: true
-- uses: github/codeql-action/upload-sarif@v3
-  if: ${{ !cancelled() }}
-  with:
-    sarif_file: mjolnir.sarif
-```
-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
-```bash
-npx mjolnir-qa@4.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
-Findings are only worth something if something acts on them.
-```text
-SCAN → EVIDENCE → HANDOFF → AGENT → RE-SCAN → PROOF
-```
-**AI writes the fix. Mjölnir verifies it.** The proof comes from the
-re-scan, never from the agent's own report of success.
-| 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:
-```bash
-claude mcp add mjolnir -- npx -y mjolnir-qa@4.0.0 mcp
-```
-Or to any client that takes an `mcpServers` block:
-```json
-{
-  "mcpServers": {
-    "mjolnir": {
-      "command": "npx",
-      "args": ["-y", "mjolnir-qa@4.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.
-<br />
+---
 ## 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.
+- **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.
-<br />
+---
-## What Mjölnir cannot tell you
+## Exit codes (frozen contract)
-- **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.
+| 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 |
+| `10` | Usage error                                                    |
+| `20` | Internal error                                                 |
-<br />
+`2` is distinct from `0`: an incomplete scan has not found nothing — it has not finished looking. No flag turns it into `0`.
-## 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                                           |
-### 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:
-[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"
-```
+## What Mjölnir cannot tell you
-Dev setup, the standing-gate commands, and the anti-creep and
-fixture-firewall laws are in [CONTRIBUTING.md](CONTRIBUTING.md).
+- 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._
+- 6 of 79 rules ship on an author 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 />
+---
 <div align="center">
 <img src="assets/readme/closing.svg" alt="Run it on your repo." width="100%" />
 ```bash
-npx mjolnir-qa@4.0.0
+npx mjolnir-qa@6.0.0
 ```
-[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>