mjolnir-qa 0.5.11 → 0.5.13

package/README.md

@@ -12,15 +12,23 @@ pipelines, reports a worthiness score, and shows exactly where trust breaks.
 [![license](https://img.shields.io/badge/license-MIT-C9A227.svg?style=flat-square&labelColor=0B0F17)](LICENSE)
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2022.18-2E8C7F.svg?style=flat-square&labelColor=0B0F17)](https://nodejs.org)
 
-English | [简体中文](README.zh.md) | [繁體中文](README.zht.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Dansk](README.da.md) | [日本語](README.ja.md) | [Polski](README.pl.md) | [Русский](README.ru.md) | [Norsk](README.no.md) | [Português (Brasil)](README.br.md) | [ไทย](README.th.md) | [Türkçe](README.tr.md) | [Українська](README.uk.md) | [বাংলা](README.bn.md) | [Ελληνικά](README.gr.md) | [Tiếng Việt](README.vi.md) | [עברית](README.he.md) | [العربية](README.ar.md) | [Bosanski](README.bs.md)
-
 ```bash
 npx mjolnir-qa@latest
 ```
 
 **Are your tests worthy of trust?**
 
-[See it work](#-see-it-work) · [Quickstart](#-quickstart) · [What it checks](#-what-mjölnir-checks) · [Scoring](#how-the-score-works) · [CI](#-ci-integration) · [Configuration](#configuration) · [Docs](#-documentation)
+[See it work](#-see-it-work) · [Quickstart](#-quickstart) · [Who it's for](#-who-is-this-for) · [Why not a linter](#-mjölnir-is-not-another-linter) · [What it verifies](#-what-mjölnir-verifies) · [Scoring](#-how-the-score-works) · [Runtime evidence](#-runtime-evidence) · [CI](#-ci-integration) · [Exit codes](#-exit-codes--contracts) · [Docs](#-documentation) · [Contributing](#-contributing)
+
+<details>
+<summary>Read this in another language — 22 translations</summary>
+
+English | [简体中文](README.zh.md) | [繁體中文](README.zht.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Dansk](README.da.md) | [日本語](README.ja.md) | [Polski](README.pl.md) | [Русский](README.ru.md) | [Norsk](README.no.md) | [Português (Brasil)](README.br.md) | [ไทย](README.th.md) | [Türkçe](README.tr.md) | [Українська](README.uk.md) | [বাংলা](README.bn.md) | [Ελληνικά](README.gr.md) | [Tiếng Việt](README.vi.md) | [עברית](README.he.md) | [العربية](README.ar.md) | [Bosanski](README.bs.md)
+
+English is canonical. Translations are machine-assisted and may lag behind
+it; `npm run docs:translations` reports how far.
+
+</details>
 
 </div>
 
@@ -29,14 +37,38 @@ npx mjolnir-qa@latest
 ## 🎬 See it work
 
 <p align="center">
-  <img src="assets/readme/demo.svg" alt="Mjölnir's full --verbose report on a demo repo: WORTHINESS 75/100 NEEDS WORK, a diagnostics-by-category breakdown, a FIX THIS FIRST list, and every finding with its rule ID and line number across CI, Playwright, test-hygiene and Python rules" width="900" />
+  <a href="assets/video/mjolnir-demo.mp4">
+    <img src="assets/video/mjolnir-demo-poster.png" alt="Mjölnir scanning a demo repo: the hammer instrument at [STRAINED] and WORTHINESS 75/100 NEEDS WORK" width="900" />
+  </a>
+</p>
+
+<p align="center">
+  <strong><a href="assets/video/mjolnir-demo.mp4">▶ Watch the 42-second demo</a></strong> —
+  one false-green CI gate: found, fixed, and re-proved.
+</p>
+
+<sub>Every frame is real CLI output. The 75 → 90 score change is a real
+re-scan after applying the fix the tool itself printed — never a mockup.
+Rendered by `npm run docs:video` from
+[`assets/video/script.demo.json`](assets/video/script.demo.json);
+[`tests/contract/video-script.spec.ts`](tests/contract/video-script.spec.ts)
+fails CI if that script stops matching what the CLI prints, or if the
+findings the video shows as fixed turn out to still be there.</sub>
+
+<details>
+<summary><strong>Prefer it inline?</strong> The full <code>--verbose</code> report, as an animated SVG</summary>
+
+<p align="center">
+  <img src="assets/readme/demo.svg" alt="Mjölnir's full --verbose report on a demo repo: WORTHINESS 75/100 NEEDS WORK, a diagnostics-by-category breakdown, a FIX THIS FIRST list, and every finding with its rule ID and line number" width="900" />
 </p>
 
 <sub>The complete `npx mjolnir-qa ./examples/demo-repo --verbose` output,
 rendered from the actual reporter — nothing trimmed. Regenerated by
 `npm run docs:demo`;
-[`tests/demo-asset-reproducibility.spec.ts`](tests/demo-asset-reproducibility.spec.ts)
-fails CI if it drifts from what the tool prints.</sub>
+[`tests/contract/demo-asset-reproducibility.spec.ts`](tests/contract/demo-asset-reproducibility.spec.ts)
+fails CI if it drifts.</sub>
+
+</details>
 
 **What just happened:**
 
@@ -48,27 +80,48 @@ fails CI if it drifts from what the tool prints.</sub>
 3. It turned each into a concrete finding with a rule ID, a location and a
    fix — and a single score you can gate a PR on.
 
+There's also an 89-second tour covering `explain`, `forensics`, and the
+rest of the walkthrough below — same pipeline, same guarantee (every
+frame is real CLI output). It's built as
+[`assets/video/script.tour.json`](assets/video/script.tour.json) but not
+committed as an MP4 (it's ~16MB; every clone shouldn't pay for a video
+most readers won't open) — run `npm run docs:video` to render it, or
+check the repo's [Releases](../../releases) for a published copy.
+
 ### One finding, up close
 
 Run `mjolnir explain QA-CI-001` on the first finding above and you get:
 
 ```text
-▚ QA-CI-001 — continue-on-error masks a failing verification gate
+  ▚ QA-CI-001 — continue-on-error masks a failing verification gate
 
 Severity:    error
 Confidence:  high
+Tier:        quarantine
 Evidence:    E2
-Measured FP: not yet measured — this rule ships on assumption (see docs/FP-AUDIT.md)
+QA impact:   False-green risk (FALSE-GREEN)
+Measured FP: 11% (19 hand-classified corpus verdicts)
+FP risk:     low (author estimate)
+Languages:   yaml
+Frameworks:  github-actions
 
 WHAT WAS FOUND (real detector output, not a mockup)
   Job `security-scan` runs a verification gate under `continue-on-error: true`.
 
 WHY IT MATTERS
-  This job can fail every day and CI will still show green. The checkmark
-  on this workflow cannot be trusted.
+  This job can fail every day and CI will still show green. The checkmark on
+  this workflow cannot be trusted.
 
 HOW TO FIX
   Remove continue-on-error, or scope it to individual non-blocking steps only.
+
+  Example from this rule's own must-fire fixture: QA-CI-001/must-fire/masked.yml
+
+HOW TO VERIFY THE FIX
+  Re-run `mjolnir` on the changed file(s) — this finding should no longer
+  appear. `mjolnir --scope changed` scopes the check to just what you touched.
+
+Docs: mjolnir rules --md   (full catalog, this rule included)
 ```
 
 That is the unit of value: not a style nit, but a place where your CI is
@@ -153,7 +206,35 @@ Requires Node.js ≥ 22.18. Works on Windows, macOS, and Linux.
 
 ---
 
-## 🔨 What Mjölnir checks
+## ⚡ Mjölnir is not another linter
+
+Linters tell you whether code follows rules. Mjölnir tells you whether your
+verification can be trusted.
+
+|                                                          | ESLint / SonarQube | Coverage tools | AI code review |   **Mjölnir**    |
+| -------------------------------------------------------- | :----------------: | :------------: | :------------: | :--------------: |
+| CI workflow integrity (`continue-on-error`, `\|\| true`) |         ❌         |       ❌       | only the diff  |        ✅        |
+| Cross-language (TS, Python, Java, C#) from one tool      |         ❌         |       ❌       |       ❌       |        ✅        |
+| Grades Playwright locator resilience (Selector Health)   |         ❌         |       ❌       |       ❌       |        ✅        |
+| Flags tests with no real assertions                      |   ✅ (plugin)\*    |       ❌       |   sometimes    |        ✅        |
+| Catches hard sleeps (`waitForTimeout`, `time.sleep`)     |   ✅ (plugin)\*    |       ❌       |   sometimes    |        ✅        |
+| Reads real run data for `TRUE-FLAKE` verdicts            |         ❌         |       ❌       |       ❌       |        ✅        |
+| Deterministic (same input → same output)                 |         ✅         |       ✅       |       ❌       |        ✅        |
+| Cost per scan                                            |        free        |      free      |     tokens     | **zero** (local) |
+
+\*`eslint-plugin-jest` (`expect-expect`) and `eslint-plugin-playwright`
+(`expect-expect`, `no-wait-for-timeout`) cover these for their respective
+frameworks.
+
+**Use AI review too.** It catches nuance, intent, and design flaws no regex
+can find. Mjölnir catches the structural patterns AI overlooks because they
+look "intentional" — a committed `.only`, a swallowed exit code, a
+`continue-on-error` on a test job. Those aren't bugs that need reasoning;
+they're facts that need scanning.
+
+---
+
+## 🔨 What Mjölnir verifies
 
 |     |                                                                                                                   |
 | --- | ----------------------------------------------------------------------------------------------------------------- |
@@ -164,12 +245,15 @@ Requires Node.js ≥ 22.18. Works on Windows, macOS, and Linux.
 | 🐍  | **All four Playwright bindings** — TypeScript, Python, Java, C#/.NET — plus pytest, JUnit/TestNG and CI workflows |
 | 🔒  | **Local-first** — zero network calls while scanning, zero telemetry, runs in seconds                              |
 
-### The rules
-
 Every rule ships with must-fire **and** must-not-fire fixtures. A rule that
 fires on its own negative fixture cannot ship — that's the false-positive
 firewall.
 
+**The rule catalog.** Every family is collapsed below; the generated
+full catalog lives in [`docs/rules/`](docs/rules/),
+[what it checks](https://sergey-bar.github.io/Mjolnir/guide/what-it-checks),
+or `mjolnir rules --md`.
+
 <details>
 <summary><strong>Test Hygiene</strong></summary>
 
@@ -285,7 +369,7 @@ firewall.
 ### How much of this is measured
 
 **78 of 99 rules carry a false-positive rate measured against real OSS code** (≥ 10 hand-classified findings each; see
-[docs/FP-AUDIT.md](docs/FP-AUDIT.md)). The other 23 ship on the author's
+[docs/FP-AUDIT.md](docs/FP-AUDIT.md)). The other 21 ship on the author's
 estimate. Every scan footer tells you how many of the rules that _fired_
 are measured; `mjolnir rules --unmeasured` lists the ones that aren't;
 every rule's `mjolnir explain` page states its status. We publish the rate
@@ -295,82 +379,42 @@ Growing that number is the project's continuing work.
 ### Rule tiers and language maturity
 
 Every rule is `core`, `extended`, or `quarantine`, assigned from its
-**measured** false-positive rate:
-
-| Tier         | Meaning                                  | Default scan | `--strict` |
-| ------------ | ---------------------------------------- | :----------: | :--------: |
-| `core`       | ≤ 10 % measured FP                       |      ✅      |     ✅     |
-| `extended`   | ≤ 30 % measured FP                       |      ✅      |     ✅     |
-| `quarantine` | above 30 %, or not yet measured (n < 10) |      ❌      |     ✅     |
-
-| Language        | Adapter      | Coverage today                                     |
-| --------------- | ------------ | -------------------------------------------------- |
-| TypeScript / JS | compiler AST | broadest, most measured — mostly `core`/`extended` |
-| Python / pytest | regex layer  | broad, corpus-audited — mostly `core`/`extended`   |
-| Java            | regex layer  | newer — mostly `extended`/`quarantine`             |
-| C# / .NET       | regex layer  | newer — mostly `extended`/`quarantine`             |
-
-TypeScript and Python have the broadest measured coverage. Java and C# ship,
-are documented, and stay out of the headline number until a real consumer
-suite (not a binding library's own tests) has been audited.
+**measured** false-positive rate — quarantine rules only run under
+`--strict`. Tiers, language maturity and the promotion/demotion rules:
+[rule lifecycle](https://sergey-bar.github.io/Mjolnir/reference/rule-lifecycle).
 
 ---
 
-## How the score works
+## 📊 How the score works
 
 <p align="center">
   <img src="assets/readme/terminal-hero.svg" alt="Mjölnir terminal output — WORTHINESS 75/100 NEEDS WORK, a diagnostics-by-category breakdown, and a FIX THIS FIRST list" width="820" />
 </p>
 
 <sub>Regenerated by `npm run docs:hero`;
-[`tests/hero-asset-reproducibility.spec.ts`](tests/hero-asset-reproducibility.spec.ts)
+[`tests/contract/hero-asset-reproducibility.spec.ts`](tests/contract/hero-asset-reproducibility.spec.ts)
 fails CI if it drifts from what the reporter actually prints.</sub>
 
 The score is transparent: **error −8, warning −3, info −1**, then normalized
 by suite exposure (deductions per test declaration). Evidence-weighted
 deductions mean weak signals cost less. The terminal shows the same
-discounted numbers the score uses — no black box. Full method:
-[docs/SCORING.md](docs/SCORING.md).
-
-**Verdicts**
+discounted numbers the score uses — no black box.
 
-| Score   | Verdict          |
-| ------- | ---------------- |
-| ≥ 80    | ✓ **WORTHY**     |
-| 50 – 79 | ⚠ **NEEDS WORK** |
-| < 50    | ✖ **UNWORTHY**   |
-
-**Evidence levels** — every finding carries one; it sets the finding's
-weight in the score:
-
-| Level | Meaning              | Score impact     | Example                                            |
-| ----- | -------------------- | ---------------- | -------------------------------------------------- |
-| E2    | Deterministic defect | Full deduction   | `.only` committed — structurally provable          |
-| E1    | Heuristic pattern    | Half deduction   | Regex-matched `sleep()` — strong signal, not proof |
-| E0    | Observation          | Zero (info only) | Reported but never gates CI or deducts             |
+| Score   | Verdict          |     | Level | Evidence             | Score impact     |
+| ------- | ---------------- | --- | ----- | -------------------- | ---------------- |
+| 100     | ⚡ **FORGED**    |     | E2    | Deterministic defect | Full deduction   |
+| ≥ 80    | ✓ **WORTHY**     |     | E1    | Heuristic pattern    | Half deduction   |
+| 50 – 79 | ⚠ **NEEDS WORK** |     | E0    | Observation          | Zero (info only) |
+| < 50    | ✖ **UNWORTHY**   |     |       |                      |                  |
 
 Most rules are **E1**. The tagline "we prove it" refers to this system:
 E2 findings are structural proof; E1 findings are correctly-positioned
 warnings, not formal proofs.
 
-An empty repo scores `null`, never a fake 100 — see [Trust model](#trust-model).
-
----
-
-## 🎭 Selector Health Score
-
-The headline metric for Playwright suites — how resilient your locators are:
-
-```text
-▚ SELECTOR HEALTH — e2e/checkout.spec.ts
-
-  [█████████████████░░░]  83 / 100
-  role/text: 2 · testid: 1 · css-chains: 1 ⚠ · xpath: 0
-```
-
-Role-based locators score full credit. CSS class chains and XPath tank the
-score — they break on any DOM refactor without telling you which behavior
-regressed.
+**No false proof.** We'd rather say "unknown" than "verified" — an empty
+repo scores `null`, never a fake 100. Full method:
+[docs/SCORING.md](docs/SCORING.md) ·
+[scoring guide](https://sergey-bar.github.io/Mjolnir/guide/scoring).
 
 ---
 
@@ -399,60 +443,6 @@ test. It gets flagged `TRUE-FLAKE` regardless of the final green checkmark.
 
 ---
 
-## ⚡ Mjölnir is not another linter
-
-Linters tell you whether code follows rules. Mjölnir tells you whether your
-verification can be trusted.
-
-|                                                          | ESLint / SonarQube | Coverage tools | Manual review | **Mjölnir** |
-| -------------------------------------------------------- | :----------------: | :------------: | :-----------: | :---------: |
-| CI workflow integrity (`continue-on-error`, `\|\| true`) |         ❌         |       ❌       |    rarely     |     ✅      |
-| Cross-language (TS, Python, Java, C#) from one tool      |         ❌         |       ❌       |      ❌       |     ✅      |
-| Grades Playwright locator resilience (Selector Health)   |         ❌         |       ❌       |    rarely     |     ✅      |
-| Flags tests with no real assertions                      |   ✅ (plugin)\*    |       ❌       |   sometimes   |     ✅      |
-| Catches hard sleeps (`waitForTimeout`, `time.sleep`)     |   ✅ (plugin)\*    |       ❌       |   sometimes   |     ✅      |
-| Runs in seconds, zero network calls while scanning       |         ✅         |       ✅       |       —       |     ✅      |
-
-\*`eslint-plugin-jest` (`expect-expect`) and `eslint-plugin-playwright`
-(`expect-expect`, `no-wait-for-timeout`) cover these for their respective
-frameworks.
-
-**Runtime analysis** is a separate category from static linting:
-
-|                                               | Playwright retry reporter | Allure / ReportPortal | **Mjölnir forensics** |
-| --------------------------------------------- | :-----------------------: | :-------------------: | :-------------------: |
-| Reads real run data for `TRUE-FLAKE` verdicts |         partial\*         |     partial (tag)     |          ✅           |
-| Flaky-triage report from execution history    |            ❌             |          ✅           |          ✅           |
-| Integrates with static worthiness score       |            ❌             |          ❌           |          ✅           |
-
-\*Playwright tracks retries internally but does not produce a standalone
-flakiness report with verdict labels.
-
----
-
-## 🤖 Why not just use AI code review?
-
-Different problem, different layer. AI review can spot a suspicious test
-change in a diff; it does not prove the verification system as a whole is
-trustworthy — and it only sees the diff you show it.
-
-|                                       | AI code review (Copilot, etc.) |         **Mjölnir**         |
-| ------------------------------------- | :----------------------------: | :-------------------------: |
-| Cost per scan                         | Tokens (scales with diff size) | **Zero** (local, installed) |
-| Sees the whole suite + all CI configs |  Only the PR diff you show it  | **Everything, every time**  |
-| Deterministic (same input → same out) |     ❌ (non-deterministic)     |           **✅**            |
-| Catches patterns dormant for months   |  Only if it's in the context   |  **✅** (scans all files)   |
-| Remembers findings between runs       | ❌ (no memory across sessions) |  **✅** (baseline + diff)   |
-| Runs without human triggering         |      Needs a PR or prompt      | **✅** (CI hook, 3 seconds) |
-
-**Use both.** AI catches nuance, intent, and design flaws no regex can
-find. Mjölnir catches the structural patterns AI overlooks because they
-look "intentional" — a committed `.only`, a swallowed exit code, a
-`continue-on-error` on a test job. Those aren't bugs that need reasoning;
-they're facts that need scanning.
-
----
-
 ## 🤖 CI integration
 
 One command generates a PR workflow — advisory by default, never blocking:
@@ -484,49 +474,6 @@ ref with `--base <ref>`.
 
 ---
 
-## Configuration
-
-Mjölnir is zero-config. An optional `mjolnir.config.json` (or
-`.mjolnir.json`) at the repo root tunes severity, gating and scope — it
-never changes detection semantics.
-
-| Key                 | Type                                 | Effect                                                                                                                                                                   |
-| ------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `exclude`           | `string[]`                           | Extra ignore globs (gitignore subset), on top of the built-in defaults                                                                                                   |
-| `gate`              | `"advisory" \| "error" \| "warning"` | Which severities exit non-zero (default `error`; `advisory` never blocks)                                                                                                |
-| `severityOverrides` | `{ "<RULE-ID>": severity }`          | Re-rank a rule's findings for your repo                                                                                                                                  |
-| `ignore`            | `IgnoreEntry[]`                      | Suppress findings — **`reason` is required**; entries expire after 90 days (an explicit `expires` date, or the config file's last-modified time for entries without one) |
-| `plugins`           | `string[]`                           | Third-party rule packages (see [Trust model](#trust-model))                                                                                                              |
-
-```json
-{
-  "gate": "error",
-  "exclude": ["legacy/**"],
-  "severityOverrides": { "QA-PW-118": "warning" },
-  "ignore": [
-    {
-      "ruleId": "QA-TEST-004",
-      "files": ["e2e/legacy-login.spec.ts"],
-      "reason": "Third-party widget needs a settle delay; tracked in JIRA-4821",
-      "expires": "2026-12-31"
-    }
-  ]
-}
-```
-
-- **`.mjolnirignore`** — a plain gitignore-style file for path exclusions,
-  same dialect as `exclude`. Use it for machine-wide noise; use `exclude`
-  when the list belongs in version control alongside the rest of the config.
-- **CLI overrides** — `--strict` (include quarantine rules), `--width <cols>`
-  and `--ascii` / `--no-ascii` (terminal rendering), `--tone blunt`
-  (blunter messages), `--max-duration <sec>` (bounded partial scan).
-- Rule suppression and deprecation lifecycle: [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md).
-
-`ignore` entries also power the standalone `mjolnir suppressions` command,
-which lists what's currently suppressed and when each entry expires.
-
----
-
 ## 📐 Exit codes & contracts
 
 Frozen — safe to build CI logic on:
@@ -546,18 +493,11 @@ are immutable once shipped and never reused.
 
 ## Trust model
 
-- **Local-first** — zero network calls during scanning. Ever. Zero telemetry.
-- **No false proof** — we'd rather say "unknown" than "verified". An empty
-  repo gets `score: null`, never a fake 100.
-- **Partial honesty** — if analysis was cut short, the output says so.
-  Never "complete" when it isn't.
-- **FP firewall** — detection runs on a comment/string-free view of the code
-  (TypeScript rules use the compiler AST): a pattern inside a prose comment
-  or a doc-example string is documentation, not a finding.
-- **Measured, not asserted** — only rules with a false-positive rate from
-  real OSS code ship in the headline tiers (see
-  [How much of this is measured](#how-much-of-this-is-measured)); the scan
-  footer and `mjolnir rules --unmeasured` tell you which is which.
+**Local-first, zero telemetry, no false proof** — full detail in
+[docs/SCORING.md](docs/SCORING.md) and
+[docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md). The one piece worth
+stating here because it changes how you invoke the tool:
+
 - **Plugin trust & execution gate** — plugins are npm packages declared
   under `"plugins"`; JS modules live in `mjolnir-rules/*.mjs`. There is
   **no sandbox**: plugin code runs with full Node privileges, the same
@@ -569,52 +509,10 @@ are immutable once shipped and never reused.
   unaffected: they declare regex patterns and execute no code by design.
   Core rule-ID prefixes are reserved and rejected from plugins and
   external rules to prevent spoofing.
-- **Workspace-local external rules** (folder-based, zero network) — a
-  `mjolnir-rules/` directory next to the scan target loads custom rules:
-  JSON files declare regex patterns (no code executed), `.mjs`/`.js`
-  modules export `rules` (full-Node trust, same as plugins). External
-  rules carry the same trust metadata as core; they can never ship in
-  the core tier (core requires a measured FP rate from the corpus
-  sidecar — a declared `tier: "core"` is clamped to `extended`), obey
-  tier caps, and are drift-checked: `mjolnir rules --md --external`
-  renders the catalog from the loaded files (provenance `external`),
-  and the matrix generator accepts `--external <root>`.
-
----
-
-## 🏗️ Architecture
-
-<details>
-<summary>Expand tree</summary>
-
-```
-mjolnir/
-├── src/
-│   ├── engine/          # LanguageAdapter interface + rule runner
-│   ├── adapters/        # typescript · python · java · csharp · github-actions
-│   ├── rules/           # rules across 8 families + the measured-FP table
-│   ├── playwright/      # Selector Health Score engine
-│   ├── discovery/       # workspace, frameworks, ignore resolution
-│   ├── scope/           # git merge-base changed-scope engine
-│   ├── scorer/          # transparent deduction table + prioritization
-│   ├── reporter/        # terminal · JSON · SARIF 2.1 · Mermaid
-│   ├── forensics/       # run-data ingestion · flake verdicts · triage
-│   ├── config/          # mjolnir.config.json + suppressions
-│   ├── plugins/         # third-party rule loading (no sandbox)
-│   └── commands/        # every subcommand
-└── tests/
-    ├── fixtures/        # must-fire / must-not-fire per rule
-    └── golden/          # frozen score regression locks
-```
-
-</details>
 
-- **Rules are pure functions** — `(SourceFileContext) → Finding[]`, no I/O,
-  no globals. Adding an ecosystem = one adapter + its rules.
-- **TypeScript/Playwright uses the compiler AST** (ts-morph). Python, Java
-  and C# run on a shared comment/string-masked regex layer.
-- A tree-sitter WASM AST layer for Java and C# exists and is the next
-  precision step — it is not yet wired into the synchronous scan pipeline.
+Architecture, the full rule catalog, and the tree-sitter roadmap live in
+[CONTRIBUTING.md](CONTRIBUTING.md) and the
+[docs site](https://sergey-bar.github.io/Mjolnir/).
 
 ---
 
@@ -623,6 +521,7 @@ mjolnir/
 | Document                                               | What's in it                                      |
 | ------------------------------------------------------ | ------------------------------------------------- |
 | [docs/SCORING.md](docs/SCORING.md)                     | Score normalization + 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 + method            |
 | [docs/RULE-LIFECYCLE.md](docs/RULE-LIFECYCLE.md)       | Rule states, suppression, deprecation             |
 | [docs/VERSIONING.md](docs/VERSIONING.md)               | Semver policy, frozen surfaces, deprecation cycle |
@@ -639,7 +538,7 @@ mjolnir/
 
 **v0.5.x · open beta.** The JSON schema and exit codes are frozen contracts.
 TypeScript and Python have the broadest measured coverage; Java and C# are
-newer — read them through the [maturity table](#rule-tiers-and-language-maturity).
+newer — read them through the [maturity table](https://sergey-bar.github.io/Mjolnir/reference/rule-lifecycle).
 Honest scope, no invented dates: the [public roadmap](https://sergey-bar.github.io/Mjolnir/reference/roadmap).
 
 ---

package/README.no.md

@@ -15,7 +15,7 @@ tilliten bryter sammen.
 
 [English](README.md) | [简体中文](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 | [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)
 
-> 🤖 Machine-assisted translation. The [English README](README.md) is canonical. Last synced: 2026-09-04.
+> 🤖 Machine-assisted translation. The [English README](README.md) is canonical. Last synced: 2026-09-07.
 
 ```bash
 npx mjolnir-qa@latest
@@ -296,14 +296,14 @@ det er false-positive-brannmuren.
 
 ### Hvor mye er målt
 
-**74 av 99 regler bærer en false-positive-rate målt mot ekte OSS-kode**
+**78 av 99 regler bærer en false-positive-rate målt mot ekte OSS-kode**
 (≥ 10 håndklassifiserte funn hver; se
-[docs/FP-AUDIT.md](docs/FP-AUDIT.md)). De andre 19 skiper på
+[docs/FP-AUDIT.md](docs/FP-AUDIT.md)). De andre 21 skiper på
 forfatterens estimat. Hver skann-fotnote forteller hvor mange av de
 _utløste_ reglene som er målt; `mjolnir rules --unmeasured` lister de
 umålte; hver regels `mjolnir explain`-side angir statusen. Vi publiserer
 raten selv når den er stygg — QA-CS-103 auditeres til 95 % og er satt i
-karantene for det. Å få de 78 til å vokse er prosjektets fortsatte
+karantene for det. Å få det tallet til å vokse er prosjektets fortsatte
 arbeid.
 
 ### Regel-tiers og språkmodenhet
@@ -454,14 +454,14 @@ Annet problem, annet lag. AI-review kan spotte en mistenkelig
 testendring i en diff; det beviser ikke at verifiseringssystemet som
 helhet er troverdig — og det ser bare diffen du viser det.
 
-|                                             |      AI-kodereview (Copilot m.fl.)      |         **Mjölnir**          |
-| ------------------------------------------- | :-------------------------------------: | :--------------------------: |
-| Kostnad per skann                           |  Tokens (skalerer med diffstørrelsen)   | **Null** (lokal, installert) |
-| Ser hele suiten + alle CI-konfigs           |         Bare PR-diffen du viser         |      **Alt, hver gang**      |
-| Deterministisk (samme input → samme output) |        ❌ (ikke-deterministisk)         |            **✅**            |
-| Fanger mønstre som har sovet i måneder      |      Bare hvis det er i konteksten      | **✅** (skanner alle filer)  |
-| Husker funn mellom kjøringer                | ❌ (ingen hukommelse på tvers av økter) |   **✅** (baseline + diff)   |
-| Kjører uten menneskelig utløser             |        Krever en PR eller prompt        | **✅** (CI-hook, 3 sekunder) |
+|                                             |      AI-kodereview (Copilot m.fl.)      |             **Mjölnir**              |
+| ------------------------------------------- | :-------------------------------------: | :----------------------------------: |
+| Kostnad per skann                           |  Tokens (skalerer med diffstørrelsen)   |     **Null** (lokal, installert)     |
+| Ser hele suiten + alle CI-konfigs           |         Bare PR-diffen du viser         |          **Alt, hver gang**          |
+| Deterministisk (samme input → samme output) |        ❌ (ikke-deterministisk)         |                **✅**                |
+| Fanger mønstre som har sovet i måneder      |      Bare hvis det er i konteksten      |     **✅** (skanner alle filer)      |
+| Husker funn mellom kjøringer                | ❌ (ingen hukommelse på tvers av økter) |       **✅** (baseline + diff)       |
+| Kjører uten menneskelig utløser             |        Krever en PR eller prompt        | **✅** (CI-hook, kjører på sekunder) |
 
 **Bruk begge.** AI fanger nyanse, intensjon og designfeil ingen regex
 kan finne. Mjölnir fanger de strukturelle mønstrene AI overser fordi de
@@ -585,11 +585,18 @@ aldri.
   ekte OSS-kode skiper i overskriftstierne (se
   [Hvor mye er målt](#hvor-mye-er-målt)); skann-fotnoten og
   `mjolnir rules --unmeasured` forteller deg hvilke som er hva.
-- **Plugin-tillit** — plugins er npm-pakker deklarert under
-  `"plugins"`. Det er **ingen sandbox**: plugin-kode kjører med fulle
+- **Plugin-tillit og kjøringsport** — plugins er npm-pakker deklarert under
+  `"plugins"`; JS-moduler bor i `mjolnir-rules/*.mjs`.
+  Det er **ingen sandbox**: plugin-kode kjører med fulle
   Node-privilegier, samme tillitsmodell som ESLint- eller
-  Vitest-plugins. Core regel-ID-prefiks er reservert og avvises fra
-  plugins mot spoofing.
+  Vitest-plugins. Derfor er kodekjøring **opt-in ved hver skann**: gi
+  `--enable-plugins` (eller sett `MJOLNIR_ENABLE_PLUGINS=1`), ellers
+  lastes kildene IKKE — et høylig stderr-varsel lister nøyaktig hva som
+  ble hoppet over. Å skanne ukjent kode kjører den aldri. JSON-regelmanifest
+  (`mjolnir-rules/*.json`) berøres ikke: de deklarerer regex-mønstre og
+  kjører ingen kode av konstruksjon. Core regel-ID-prefiks er reservert
+  og avvises fra
+  plugins og eksterne regler mot spoofing.
 - **Workspace-lokale eksterne regler** (mappebaserte, null nettverk) —
   en `mjolnir-rules/`-mappe ved siden av skannemålet loader
   tilpassede regler: JSON-filer deklarerer regex-mønstre (ingen kode

package/README.pl.md

@@ -15,7 +15,7 @@ gdzie zaufanie się łamie.
 
 [English](README.md) | [简体中文](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.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)
 
-> 🤖 Machine-assisted translation. The [English README](README.md) is canonical. Last synced: 2026-09-04.
+> 🤖 Machine-assisted translation. The [English README](README.md) is canonical. Last synced: 2026-09-07.
 
 ```bash
 npx mjolnir-qa@latest
@@ -297,14 +297,14 @@ nie może się wydać — to zapora na fałszywe pozytywy.
 
 ### Ile z tego jest zmierzone
 
-**74 z 99 reguł niesie stopę fałszywych pozytywów zmierzoną na
+**78 z 99 reguł niesie stopę fałszywych pozytywów zmierzoną na
 prawdziwym kodzie OSS** (≥ 10 ręcznie zaklasyfikowanych znalezisk każda;
-zob. [docs/FP-AUDIT.md](docs/FP-AUDIT.md)). Pozostałe 19 wychodzi na
+zob. [docs/FP-AUDIT.md](docs/FP-AUDIT.md)). Pozostałe 21 wychodzi na
 oszacowaniu autora. Stopka każdego skanu mówi, ile z _odpalonych_
 reguł jest zmierzonych; `mjolnir rules --unmeasured` wypisuje
 niezmierzone; strona `mjolnir explain` każdej reguły deklaruje jej
 status. Publikujemy stopę, nawet gdy jest brzydka — QA-CS-103 audytuje
-się na 95 % i za to trafia do kwarantanny. Powiększanie tej 78-ki to
+się na 95 % i za to trafia do kwarantanny. Powiększanie tej liczby to
 stale trwająca praca projektu.
 
 ### Tiery reguł i dojrzałość językowa
@@ -465,7 +465,7 @@ godny zaufania — i widzi tylko diff, który mu pokażesz.
 | Deterministyczny (ten sam input → ten sam output) |     ❌ (niedeterministyczny)      |              **✅**               |
 | Łapie wzorce śpiące miesiącami                    |   Tylko jeśli jest w kontekście   | **✅** (skanuje wszystkie pliki)  |
 | Pamięta znaleziska między przebiegami             | ❌ (brak pamięci między sesjami)  |     **✅** (baseline + diff)      |
-| Działa bez ludzkiego wyzwalacza                   |   Potrzebuje PR-a albo promptu    |    **✅** (hak CI, 3 sekundy)     |
+| Działa bez ludzkiego wyzwalacza                   |   Potrzebuje PR-a albo promptu    |  **✅** (hak CI, działa sekundy)  |
 
 **Używaj obu.** AI łapie niuans, intencję i wady projektowe, których
 żaden regex nie znajdzie. Mjölnir łapie strukturalne wzorce, które AI
@@ -587,11 +587,19 @@ są niezmienne po wydaniu i nigdy nie są używane ponownie.
   reguły ze stopą fałszywych pozytywów z prawdziwego kodu OSS (zob.
   [Ile z tego jest zmierzone](#ile-z-tego-jest-zmierzone)); stopka
   skanu i `mjolnir rules --unmeasured` powiedzą ci, które które.
-- **Zaufanie do pluginów** — pluginy to pakiety npm deklarowane pod
-  `"plugins"`. **Nie ma sandboxa**: kod pluginu działa z pełnymi
+- **Zaufanie do pluginów i brama wykonania** — pluginy to pakiety npm
+  deklarowane pod
+  `"plugins"`; moduły JS żyją w `mjolnir-rules/*.mjs`.
+  **Nie ma sandboxa**: kod pluginu działa z pełnymi
   uprawnieniami Node, ten sam model zaufania co pluginy ESLint czy
-  Vitest. Prefiksy ID reguł core są zarezerwowane i odrzucane od
-  pluginów przeciw spoofingowi.
+  Vitest. Dlatego wykonanie kodu jest **opt-in przy każdym skanie**:
+  przekaż `--enable-plugins` (albo ustaw `MJOLNIR_ENABLE_PLUGINS=1`),
+  inaczej źródła NIE są ładowane — głośny komunikat na stderr wylicza
+  dokładnie, co pominięto. Skanowanie niezaufanego kodu nigdy go nie
+  wykonuje. Manifesty reguł JSON (`mjolnir-rules/*.json`) nie są
+  dotknięte: deklarują wzorce regex i z założenia nie wykonują kodu.
+  Prefiksy ID reguł core są zarezerwowane i odrzucane od
+  pluginów i zewnętrznych reguł przeciw spoofingowi.
 - **Zewnętrzne reguły lokalne wobec workspace'u** (folderowe, zero
   sieci) — katalog `mjolnir-rules/` obok celu skanu ładuje własne
   reguły: pliki JSON deklarują wzorce regex (żaden kod nie jest