mjolnir-qa 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -11,12 +11,330 @@ once shipped, so this file is the record of what changed between versions.
 
 ## [Unreleased]
 
+### Breaking changes
+
+- **`business-case` no longer prints a dollar figure you did not supply.** The
+  `--industry` flag selected from a table of invented incident costs (fintech
+  $50 000, healthcare $100 000, …) with no source, and the product of that table
+  and a measured false-positive rate was printed as "Expected Savings" and
+  "Total potential savings". Pass `--incident-cost <n>` to see the arithmetic;
+  the measured FP rates, their sample sizes and the evidence weight behind them
+  are always shown. `--industry`, `--history` and `--projected` now exit with a
+  reason: `--history` read no history despite promising estimates from scan
+  improvements, and `--projected` divided the total by six and called the
+  quotient a monthly rate.
+- **`enterprise sso` and `enterprise compliance` no longer write files.** They
+  wrote an SSO guide instructing readers to add an `sso` block to
+  `mjolnir.config.json` — a key nothing reads — and three auditor-facing SOC 2 /
+  HIPAA / PCI-DSS templates mapping controls to capabilities this product does
+  not have (SSO/SAML integration, a scan "audit trail", a "privacy scan"). Both
+  now refuse with a reason. `enterprise config` emits
+  `capability-manifest.json`, whose `notProvided` list records the absences
+  instead of inventing a deployment.
+- **The evidence descriptor is now the same on every surface.** The HTML and
+  Markdown trust reports showed four bare words (`E2 · deterministic`) where the
+  terminal showed the full descriptor. They now show
+  `[E2 · deterministic · measured FP 8% · n=14 · trust L3 · runtime: file executed]`.
+  A finding with no `evidenceLevel` of its own now derives one from its type and
+  confidence instead of defaulting to `E2` — the strongest claim the product can
+  make, previously asserted for findings nobody had measured.
+- **Unmeasured counts read "unknown — not measured", not `0`.** The trust
+  report, the PR comment and the step summary all rendered
+  `testDeclarationCount ?? 0` as "0 tests analyzed in 0 files" for a producer
+  that had never measured a declaration. The trust-report JSON twin now emits
+  `null` for those fields. A zero is a claim; an absent measurement is not.
+- **The dashboard no longer varies between runs of an unchanged repository.**
+  The generation timestamp moved out of the visible body into
+  `<meta name="mjolnir-generated-at">`, and `--deterministic` omits it entirely
+  so the artifact is byte-identical and can be diffed in review.
+- **Score bands are decided in one place.** The dashboard split at 60 while the
+  terminal split at 80, so a score the terminal called UNWORTHY rendered amber
+  in HTML; the contributor handover used 90; `mermaid.ts` and
+  `monorepo-analysis.ts` each carried their own copy. All of them now read
+  `src/reporter/presentation.ts`.
+
+### Added
+
+- **Opt-in Sentry crash reporting.** Set `SENTRY_DSN` and the CLI and the MCP
+  stdio server report their own fatal errors — release-tagged as
+  `mjolnir-qa@<version>`, tagged by surface, and nothing else: no user data
+  (`sendDefaultPii: false`), no traced spans (`tracesSampleRate: 0`), no
+  findings or file contents. With no DSN the SDK is never even imported, so the
+  default install gains no dependency, no startup cost, and no network call. A
+  tool that reads private repositories must not phone home on its own, so the
+  DSN is the only switch. `@sentry/node` is an OPTIONAL peer dependency for the
+  same reason: ~1.5 MB that nothing in a code scanner needs. Capture points are
+  the two existing top-level catch blocks rather than `uncaughtException` /
+  `unhandledRejection` handlers, which would have changed the frozen exit-code
+  contract. `npm run sentry:release` creates the release and uploads source maps
+  (the build now emits them; the published tarball still excludes them).
+- `npm run report:honesty` — no surface may print a zero for a measurement that
+  may be absent. Four reviewed exceptions are recorded for computation inputs,
+  each with a reason and a follow-up.
+- `npm run thresholds:parity` — no score-band literal may exist outside the
+  threshold registry. It immediately caught a selector-health threshold that
+  shared a number with a trust band but not a meaning.
+- `npm run claims:revalidate` — every claim asserted `fixed` must rest on a
+  candidate-bound, independent revalidation. It rejects evidence that cites the
+  artifact it is meant to prove, and downgrades rather than deleting a claim
+  that loses its evidence.
+- `npm run verbs:budget` — the 5.x law, ratcheted at 50 verbs with a 44 target
+  for 5.0.
+- `npm run script:paths` — no `package.json` script may name a `tests/`,
+  `src/`, `scripts/`, `docs/`, `site/` or `enterprise/` path that does not
+  exist. 107 path references are checked today.
+- `npm run m26:gaps:revalidate` — re-runs every gap row's own
+  `revalidation_command` against the working tree and records the exit code and
+  the commit it ran at.
+- `tests/contract/artifact-determinism.spec.ts` — two runs of the HTML
+  artifact over an unchanged repository must be byte-identical.
+- `src/reporter/presentation.ts` — the one module that makes a presentation
+  decision. It reads a finding, a score or a palette and returns the word, band
+  or descriptor to print. It opens no file, touches no clock and formats no
+  document, and a test enforces that.
+
+### Fixed
+
+- **`frontier:contracts` was reporting 19 suites it never ran.** It named 24
+  test files; nineteen had been deleted by the `cc5fcb88` cleanup and its
+  follow-up. Vitest treats a missing path as "no tests here" rather than an
+  error, so the script exited 0 and printed "57 passed" while nineteen contract
+  suites — including every `m3x`/`m4x`/`m5x` frontier contract — silently did
+  not execute. A missing test file and a green test file are indistinguishable
+  from the outside, so a gate that passes because its subject is absent has
+  certified nothing. The list is rebuilt from the 23 contract suites that
+  exist (1 110 tests, not 57), and `npm run script:paths` now fails the build if
+  any `package.json` script names a path that is gone.
+- The certification ladder's language vocabulary could not name the answer its
+  own admission gate produces. `admit()` returns `UNMEASURED` as the supported
+  state of any claim not backed by evidence, but `LANGUAGE_STATE_RANK` had no
+  word for it — so a language claiming `CERTIFIED` with an empty cohort was
+  handed a result its own vocabulary could not record. `UNMEASURED` is now
+  expressible in both vocabularies, and the four rule-level states
+  (`MEASURED-CORE` … `PROVISIONAL`) are declared in `RULE_ONLY_STATES` as
+  explicitly _not_ language outcomes rather than being filtered out by a
+  hand-maintained list.
+- The contributor handover reported "Welcome aboard — the suite is in good
+  shape" whenever no issues were found, including when no run report had been
+  ingested and flakiness was therefore unmeasured. It now says what it did not
+  check.
+- The confidence table's row labels were encoded as `"k|v"` strings and split
+  back apart, so any value containing a pipe was silently truncated. The rows
+  are typed pairs. The table also gained a `<caption>`, a `<thead>` and
+  `scope` attributes; it was previously a bare `<tbody>` a screen reader
+  announced as six unlabelled rows.
+- `handoff` and `summary` each carried a private colourless score bar that
+  rendered 99 and 100 identically. Both now use the canonical `scoreGauge`, and
+  the redundant `theme.meter` alias is gone.
+- The gap ledger gained three revalidation statuses
+  (`ALREADY_FIXED` / `CONFIRMED_STILL_OPEN` / `STALE_UNVERIFIABLE`). A row may
+  no longer be cleared without a revalidation that was actually run at a named
+  commit, and `STALE_UNVERIFIABLE` deliberately does not clear a release gate —
+  an unverifiable claim must never be able to unblock a release.
+- `m26:github:sync` derived every one of 429 issue dispositions from GitHub's
+  own `state` field — a pure function of its input, containing no engineering
+  judgement — and `GAP-M26-002` then marked that script `fixed`, citing the
+  artifacts it produces. Dispositions now come from
+  `docs/issue-dispositions.json`, where each entry must carry a non-empty
+  reason and a verification naming a command or a source path, and may not be
+  verified by the script that wrote it. An untriaged issue stays open and is
+  flagged, never guessed and never silently closed. 215 of 429 are now visibly
+  awaiting a human decision, which is the honest count.
+
+### Documentation
+
+- `PRODUCT-ENHANCEMENT-ANALYSIS.md` is marked `SUPERSEDED-BY: BITTERSWEET` and
+  gained a section XII auditing its "all 16 features shipped" claims: six do not
+  hold (two shipped fabricated values, two shipped a different capability than
+  described, two never shipped). The document is kept as the record of what was
+  believed on 2026-09-20, because deleting it would destroy the only evidence
+  that the belief was wrong.
+- `docs/RELEASE-TRAINS.md` now records why each of the six scheduled verb
+  removals is justified differently, so the deprecation notices do not all send
+  the same message to users who acted on different output.
+
+## [4.0.0] — 2026-09-26
+
+The first release whose reporting surface is checked against the working tree
+rather than against a plan. Every box below is enforced by a gate in
+`npm run certify`.
+
+### What you get, relative to 3.0.0
+
+**The product no longer reports numbers it did not measure.**
+
+- [x] A scan that finished now says it finished. A minified bundle or a lockfile
+      in the repository used to downgrade a complete scan to `PARTIAL`, and the
+      terminal told you "some files were not analyzed, so the surface is
+      unverified" when every discovered test file _had_ been analyzed. Across
+      the 37-repository corpus, complete scans went from 13/37 to 29/37.
+- [x] Unmeasured counts read `unknown — not measured`, not `0`. The trust report,
+      the PR comment and the step summary all printed "0 tests analyzed in 0
+      files" for a producer that had never measured a test declaration. A zero
+      is a claim; an absent measurement is not.
+- [x] `handover` no longer tells you "the suite is in good shape" when no run
+      report was ingested and flakiness was therefore never checked. It now
+      names what it did not check.
+- [x] The HTML dashboard produces the same bytes for the same repository. It
+      embedded `new Date()` in its visible body, so it could never be diffed in
+      review. `--deterministic` omits the timestamp entirely.
+- [x] The trust report's evidence descriptor is the terminal's, on every surface.
+      HTML and Markdown showed four bare words (`E2 · deterministic`) where the
+      terminal showed the measured FP rate, the sample size, the trust rung and
+      what the runtime actually corroborated.
+- [x] A finding with no evidence level derives one from its own type and
+      confidence. It used to default to `E2` — the strongest claim the product
+      can make — for findings nobody had measured.
+- [x] The contributor handover no longer derives a dollar figure from a table of
+      invented incident costs. `business-case` multiplied a measured
+      false-positive rate by unsourced per-industry costs and printed the product
+      as "Expected Savings". A cost figure now requires `--incident-cost`, so the
+      number is yours. `--history` (which read no history) and `--projected`
+      (which divided by six) are gone, with reasons.
+- [x] `mjolnir enterprise` no longer writes a deployment config claiming
+      `sso-saml`, an SSO guide telling you to add a config key nothing reads, or
+      auditor-facing SOC 2 / HIPAA / PCI-DSS templates mapping controls to
+      capabilities this product does not have. `sso` and `compliance` refuse;
+      `config` emits a capability manifest whose `notProvided` list records the
+      absences.
+- [x] The dependency graph no longer prints a count derived from nothing.
+      "Reachable files: N" was always the number of files that went in.
+
+**The product now sees things it was blind to.**
+
+- [x] Node-native TypeScript tests (`.test.mts`, `.spec.mts`, `.test.cts`,
+      `.spec.cts`) are scanned. They were not mis-scored — they were never
+      scanned, so every rule was silent on them with no finding and no note.
+      Verified with two byte-identical tests: the `.ts` copy produced the
+      finding, the `.mts` copy produced nothing at all.
+- [x] The CI matrix installs cleanly on all three platforms. `npm ci` failed on
+      every job before a test ran, and then failed again with a missing
+      `lightningcss` binary for Linux, because a lockfile regenerated on Windows
+      cannot contain the other platforms' optional dependencies.
+
+**The gates now catch these instead of the next person.**
+
+- [x] `report:honesty` — no surface may print a zero for an absent measurement.
+      Four reviewed exceptions, each with a reason and a follow-up.
+- [x] `thresholds:parity` — no score-band literal outside the registry. It
+      immediately caught a selector-health threshold that shared a number with a
+      trust band but not a meaning.
+- [x] `script:paths` — no `package.json` script may name a path that is missing
+      or uncommitted. It found `frontier:contracts` naming 19 test files deleted
+      by an earlier cleanup: Vitest treats a missing path as "no tests here", so
+      the script exited 0 reporting "57 passed" while nineteen contract suites
+      never ran. Rebuilt from the 23 that exist — 1 110 tests, not 57.
+- [x] `lockfile:platforms` — the lockfile must carry the optional binaries for
+      every platform CI builds on. The failure is invisible locally by
+      construction, so it needed a gate that runs everywhere.
+- [x] `claims:revalidate` — a claim asserted `fixed` must rest on a
+      candidate-bound, independent revalidation. It rejects evidence citing the
+      artifact it is meant to prove, and downgrades rather than deletes a claim
+      that loses its evidence.
+- [x] `verbs:budget` — the 5.x law: one new verb requires one removal or a merge.
+- [x] `m26:gaps:revalidate` — re-runs each gap row's own command and records the
+      exit code and the commit it ran at.
+- [x] `release:verify` reports every blocker in one run. It was a `&&` chain, so
+      it stopped at the first of four and you met them one per run.
+- [x] The coverage gate is a floor and a ratchet, not one number pretending to
+      be both.
+
+**Truth in the project's own records.**
+
+- [x] The gap ledger was revalidated: all 17 rows had their own
+      `revalidation_command` run against this tree. `GAP-M26-005` read
+      `fixed` / PASS while its command _fails_. A cleared row can no longer
+      exist without a revalidation bound to a named commit, and
+      `STALE_UNVERIFIABLE` deliberately cannot unblock a release.
+- [x] **A gap row could be marked fixed while its own revalidation failed.**
+      The `exit_code === 0` check was reachable through only one of the four
+      combinations the schema allows, so a `fixed` row — or an
+      `ALREADY_FIXED` row carrying closure evidence — was accepted with
+      `exit_code: 1` recorded in its own revalidation. Three of those four
+      routes cleared the row. The test that covered it hid the hole, because
+      the fixture only set `closure_evidence` for `fixed`.
+- [x] The 429 GitHub dispositions no longer derive from GitHub's own `state`
+      field. A snapshot cannot prove itself; each disposition now needs a reason
+      and a verification. 215 issues are visibly awaiting a human decision,
+      which is the honest count.
+- [x] `PRODUCT-ENHANCEMENT-ANALYSIS.md` claimed 16 shipped features; six do not
+      hold. It is marked `SUPERSEDED-BY` and carries a per-feature audit, kept
+      rather than deleted because deleting it would destroy the only evidence
+      that the belief was wrong.
+
+**Found by the pre-release bug sweep, after the fix list was written.** Both
+were live in 3.0.0 and neither was in the plan.
+
+- [x] `mjolnir business-case <path>` answered a path that does not exist with
+      exit 0 and a clean report: "Measured: 0 of 0 findings carry a
+      corpus-measured FP rate". It called `runScan` directly and so never
+      passed through `validateScanTarget` — the check whose own comment says a
+      typo'd CI path must be a loud red, never a silent green. Thirteen of the
+      fifteen scanning verbs were already loud; this one was not, and a green
+      table over a path that was never scanned is the most dangerous output
+      this product can produce. Now exit 10.
+- [x] The extended TypeScript test-file regex was probed against 27 shapes:
+      all 12 that must match do, all 15 that must not are rejected —
+      including `a.min.mts`, `a.spec.cts.bak` and `notatest.mts`.
+- [x] `ships()` in `script:paths` was probed for the failure modes a new gate
+      usually has: an empty directory, a directory holding only untracked
+      files, and a symlink loop. All resolve correctly and none hangs. A
+      first version treated a directory as "tracked" only if `git ls-files`
+      listed the directory itself, which it never does — that produced two
+      false positives and is fixed.
+
+### Known open, deliberately
+
+- [ ] `CERTIFICATION_STATES` is not in ladder order, so `rankOf` — the only
+      ordering function — ranks `KNOWN` above `TRUST-COMPLETE`, and
+      `requiresEvidence` asks `BLOCKED` and `DEGRADED` for a corpus their own
+      doc comment says they need none. Two `it.fails` tests record it, so
+      reordering the array fails the build. Fixing it moves `rankOf` for every
+      state and changes admission outcomes, so it is a contract change, not a
+      patch.
+- [ ] 23 corpus count-drifts are unreviewed, the largest being `QA-PY-007`
+      firing 1332 times in apache-airflow and 92 now. Not accepted: running
+      `--update` without reading them would delete the only evidence that
+      detection changed.
+- [ ] 8 of 37 corpus repositories report `PARTIAL` because test-support files
+      under `__tests__/` are not scanned. The verdict is honest — an incomplete
+      scan is not a pass — and the fix is a design decision about what "the
+      surface" means, not a patch.
+- [ ] 215 of 229 GitHub issues are untriaged. Prepared dispositions exist in
+      `docs/issue-dispositions.json`; none has been applied, because closing a
+      public issue is destructive and is a person's decision.
+- [ ] `BW-022` (one workspace model, real graph edges) is open. The plan claimed
+      it is "what makes `impact` honest"; it is not — `impact` never used the
+      graph and is honest on its own path. The graph is a no-op on an unshipped
+      code path, and the function now reports that instead of implying otherwise.
+
+### Upgrade notes
+
+- Node-native TypeScript test files are now scanned, so a project using
+  `.mts`/`.cts` tests **will see new findings**. That is the fix working, not a
+  regression.
+- `business-case` requires `--incident-cost` for any dollar figure, and now
+  exits 10 on a target that does not exist instead of printing an empty report.
+- `enterprise sso` and `enterprise compliance` now exit non-zero with a reason.
+- The trust report JSON's `tests.files` and `tests.declarations` are `null`
+  rather than `0` when unmeasured.
+
+## [4.0.0-rc.1] — 2026-09-25
+
+### Breaking changes
+
+- The next published version must be a new major line. Generated CI is now
+  advisory-first while the direct composite Action remains blocking by default;
+  suppression metrics changed from configured to matched findings, and
+  zero-finding output no longer implies a clean or green suite. Publishing
+  these changes as another `3.0.0` is prohibited.
+
 ### Changed
 
-- **Advisory-first CI adoption** — `mjolnir ci install` and the root
-  GitHub Action now default to non-blocking findings and non-blocking partial
-  scans. Blocking remains explicit through `--gate error`, `--gate warning`,
-  or `fail-on`.
+- **Advisory-first generated CI adoption** — `mjolnir ci install` now
+  defaults to non-blocking findings and non-blocking partial scans. The direct
+  composite Action remains blocking by default. Blocking behavior is explicit
+  through `--gate error`, `--gate warning`, or `fail-on`.
 - Suppression counts now report matched findings, not configured entries;
   `suppression-gate` evaluates all-tier pre-suppression findings and enforces
   total-count limits.
@@ -34,6 +352,44 @@ once shipped, so this file is the record of what changed between versions.
   before it ships; and `scripts/check-ci-local-parity.mjs`, which keeps
   `ci.yml`, `merge-verify.yml` and the local gate exercising the same
   command list. All additive — no frozen surface changed.
+- **M26–M50 execution ledger** — added `docs/ROADMAP.yaml`, dated GitHub
+  issue/milestone/PR reconciliation, explicit issue dispositions, an
+  append-only gap ledger, a finite support matrix, and an external-validation
+  record. Approval authority and staged dependency resolution are recorded;
+  external evidence remains `BLOCKED`/`NOT_RUN` and cannot be synthesized.
+- **Provisional capability contracts** — added bounded, non-promoting
+  contracts for runtime evidence, provider capabilities, QA domain records,
+  agent decision receipts, plugin packs, change intelligence, mutation
+  sensitivity, adversarial challenges, simulation, language/framework packs,
+  cross-repository systems, history, detector lifecycle, research, benchmark,
+  scale, UX parity, and Trust OS release proofs. Each has focused hostile,
+  stale, foreign, malformed, and recovery coverage.
+- **Release control surfaces** — added exact version-surface synchronization,
+  RC-aware changelog validation, candidate manifest refresh/readiness,
+  reporter ramp policy, fail-closed M26 audit gates, and current-major-only
+  Action tag maintenance.
+- **README release preparation** — canonical and translated README install
+  references, release-status blocks, and new command rows are synchronized to
+  `3.0.0`; English fallback blocks are explicitly marked for human translation
+  review, and the canonical README states the certification boundary.
+- **Release proof hardening** — stable publication now generates and attaches
+  an SPDX SBOM, rejects same-version registry artifacts with a different
+  integrity digest, updates only the current `v3` Action major, and never
+  clobbers release assets.
+- **Support matrix reconciliation** — 136 cells are classified as 90 tested,
+  44 explicitly blocked, and 2 not applicable, with evidence paths and revisit
+  triggers checked locally.
+
+### Fixed
+
+- Corpus runs now record complete rule-crash provenance, reject parser
+  fallbacks, and support a provenance-only refresh that cannot update counts.
+- QA-PY-004 sanitizes assertion roots before constructing a pattern, removing
+  corpus crashes caused by nested call-like targets.
+- Pathological stress runs no longer mask crashes with `|| true`; soak evidence
+  no longer claims parent-process RSS as child memory.
+- Exact registry-install smoke can install and verify a published version
+  instead of substituting the checkout tarball.
 
 ## [3.0.0] — 2026-09-24
 
@@ -286,8 +642,6 @@ Complete implementation of the Mjolnir Master Engineering Roadmap & Product Spec
 - `src/commands/doctor.ts` gains check 11 (rule metadata contract validation).
 - 4 fingerprint implementations consolidated into `src/engine/finding-identity.ts`.
 
-## [Unreleased] — Nordic brand pass
-
 ### Changed
 
 - Terminal report: section headers are marked `▍ TITLE` instead of

package/README.ar.md

@@ -18,7 +18,7 @@
 [![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@latest
+npx mjolnir-qa@3.0.0
 ```
 
 [شاهده وهو يعمل](#شاهده-وهو-يعمل) · [البدء السريع](#البدء-السريع) · [ما الذي يكتشفه](#ما-الذي-يكتشفه-mjölnir) · [الدرجة](#درجة-الجدارة) · [الأدلة](#نموذج-الأدلة) · [تحليل التشغيلات](#تحليل-تشغيلات-الاختبار) · [CI](#سلامة-ci) · [الوكلاء](#وكلاء-الذكاء-الاصطناعي) · [الأمان](#الثقة-والأمان) · [الحدود](#ما-لا-يستطيع-mjölnir-أن-يخبرك-به) · [التوثيق](#التوثيق)
@@ -28,9 +28,9 @@ npx mjolnir-qa@latest
 
 [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](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) | العربية | [Bosanski](README.bs.md)
 
-> 🤖 Machine-assisted translation. The [English README](README.md) is canonical. Last synced: 2026-09-15.
+> 🤖 Machine-assisted translation. The [English README](README.md) is canonical. Last synced: 2026-09-26.
 
-<!-- Source hash: 3541b09e8d04 -->
+<!-- Source hash: `de04dfb1677b` -->
 
 </details>
 
@@ -38,6 +38,20 @@ npx mjolnir-qa@latest
 
 <br />
 
+## Release status (English canonical)
+
+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.
+
+> Machine-assisted canonical text. Translate this block before treating it as localized copy.
+
 ## علامة الصح الخضراء ادعاء، وليست دليلًا
 
 علامة الصح الخضراء تعني أن خط CI لم يفشل. لا تعني أن الاختبارات عملت، ولا أنها كان يمكن أن تفشل. كل واحدة من هذه تمر باللون الأخضر:
@@ -58,7 +72,7 @@ npx mjolnir-qa@latest
 
 <sub>كل نتيجة أبلغ عنها فحص العرض لهذا الـ workflow، عند السطر الذي أبلغ عنه. مولَّد بواسطة `npm run docs:readme-brand` من [`demo-report.json`](assets/readme/demo-report.json) ومقفل ضد الانحراف في CI.</sub>
 
-**الوضع الصارم.** الكشف الأكثر عدوانية — `.only`، `continue-on-error`، الاختبارات الفارغة، إساءة إعادة المحاولة — تقع في مستوى الحجر الصحي. تعمل فقط مع `--strict` وتُ限定 بخطورة `info`: تُعلم، لكنها لا تُوقف أبدًا. الفحص الافتراضي (`npx mjolnir-qa@latest` بدون `--strict`) يغطي القواعد الأساسية والموسعة فقط. أضف `--strict` عندما تريد طبقة الاستشارات أيضًا.
+**الوضع الصارم.** الكشف الأكثر عدوانية — `.only`، `continue-on-error`، الاختبارات الفارغة، إساءة إعادة المحاولة — تقع في مستوى الحجر الصحي. تعمل فقط مع `--strict` وتُ限定 بخطورة `info`: تُعلم، لكنها لا تُوقف أبدًا. الفحص الافتراضي (`npx mjolnir-qa@3.0.0` بدون `--strict`) يغطي القواعد الأساسية والموسعة فقط. أضف `--strict` عندما تريد طبقة الاستشارات أيضًا.
 
 يقرأ Mjölnir مجموعة الاختبارات وملفات workflow الخاصة بـ CI، وتقرير تشغيل حقيقي إن وُجد. لا يشغّل اختباراتك، ولا يثبّت اعتمادياتك، ولا ينفّذ الشيفرة التي يفحصها. وعندما لا يملك دليلًا، يقول ذلك بدل أن يختلق ثقة:
 
@@ -93,7 +107,7 @@ npx mjolnir-qa@latest
 
 <p align="center">
   <a href="assets/video/mjolnir-demo.mp4">
-    <img src="assets/video/mjolnir-demo-poster.png" alt="لقطة من تسجيل العرض: npx mjolnir-qa@latest يفحص مستودع العرض في نافذة طرفية" width="900" />
+    <img src="assets/video/mjolnir-demo-poster.png" alt="لقطة من تسجيل العرض: npx mjolnir-qa@3.0.0 يفحص مستودع العرض في نافذة طرفية" width="900" />
   </a>
 </p>
 
@@ -162,7 +176,7 @@ Docs: mjolnir rules --md   (full catalog, this rule included)
 ## البدء السريع
 
 ```bash
-npx mjolnir-qa@latest
+npx mjolnir-qa@3.0.0
 ```
 
 يفحص الدليل الحالي ويطبع Trust Report: ما الذي وجده، وإلى أي حد يمكنك الوثوق به، ولماذا، وما الخطوة التالية. ويخرج بالرمز `0` عندما لا يُعثر على شيء عند مستوى البوابة أو فوقه.
@@ -170,24 +184,39 @@ npx mjolnir-qa@latest
 في CI، افحص فقط ما أدخله الفرع، حتى لا تُغرق مجموعة اختبارات قديمة أول pull request لك:
 
 ```bash
-npx mjolnir-qa@latest --scope changed
+npx mjolnir-qa@3.0.0 --scope changed
 ```
 
-يكتب `mjolnir ci install` ذلك كـ workflow لـ GitHub Actions، باستخدام [الـ action](https://github.com/Sergey-Bar/Mjolnir#readme) المثبّت على الوسم الرئيسي `v1` (أو `npx` عادي مع `--no-action`). ويبقى استشاريًا إلى أن تقرر أنه يجب أن يمنع الدمج.
-
-| الأمر                               | ما الذي يفعله                                                |
-| ----------------------------------- | ------------------------------------------------------------ |
-| `mjolnir`                           | ‏Trust Report: الحكم، ودرجة الثقة، والإجراء التالي           |
-| `mjolnir --scope changed`           | فقط ما أدخله فرعك (صيغة CI)                                  |
-| `mjolnir ci install`                | ينشئ workflow استشاريًا لطلبات الدمج (قائمًا على الـ action) |
-| `mjolnir explain QA-CI-001`         | ماذا ولماذا وكيف يُصلح، مع معدل FP المقيس                    |
-| `mjolnir why src/a.spec.ts:42`      | لماذا عُلّم هذا السطر بالتحديد. لا يمنع الدمج أبدًا.         |
-| `mjolnir forensics ./test-results/` | أدلة وقت التشغيل من تشغيل حقيقي                              |
-| `mjolnir trust-report`              | ‏Trust Artifact مستقل (md + json)                            |
-| `mjolnir handoff`                   | خطة معالجة لوكيل برمجة                                       |
-| `mjolnir --json` / `--format sarif` | مخرجات قابلة للقراءة آليًا، GitHub Code Scanning             |
-| `mjolnir --format codequality`      | تقرير GitLab Code Quality (عنصر لأداة طلب الدمج)             |
-| `mjolnir --strict`                  | يشغّل أيضًا قواعد مستوى quarantine (خطر FP أعلى)             |
+يكتب `mjolnir ci install` ذلك كـ workflow لـ GitHub Actions، باستخدام [الـ action](https://github.com/Sergey-Bar/Mjolnir#readme) المثبّت على الوسم الرئيسي `v3` (أو `npx` عادي مع `--no-action`). ويبقى استشاريًا إلى أن تقرر أنه يجب أن يمنع الدمج.
+
+| الأمر                                         | ما الذي يفعله                                                |
+| --------------------------------------------- | ------------------------------------------------------------ |
+| `mjolnir`                                     | ‏Trust Report: الحكم، ودرجة الثقة، والإجراء التالي           |
+| `mjolnir --scope changed`                     | فقط ما أدخله فرعك (صيغة CI)                                  |
+| `mjolnir ci install`                          | ينشئ workflow استشاريًا لطلبات الدمج (قائمًا على الـ action) |
+| `mjolnir business-case`                       | ROI estimate: projected savings per finding                  |
+| `mjolnir release-report`                      | Release readiness: GO, CONDITIONAL GO, or NO-GO              |
+| `mjolnir release-trust`                       | 12-dimension release assurance verdict                       |
+| `mjolnir report`                              | Generate a Playwright-compatible report                      |
+| `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`                   | ماذا ولماذا وكيف يُصلح، مع معدل FP المقيس                    |
+| `mjolnir why src/a.spec.ts:42`                | لماذا عُلّم هذا السطر بالتحديد. لا يمنع الدمج أبدًا.         |
+| `mjolnir forensics ./test-results/`           | أدلة وقت التشغيل من تشغيل حقيقي                              |
+| `mjolnir trust-report`                        | ‏Trust Artifact مستقل (md + json)                            |
+| `mjolnir handoff`                             | خطة معالجة لوكيل برمجة                                       |
+| `mjolnir --json` / `--format sarif`           | مخرجات قابلة للقراءة آليًا، GitHub Code Scanning             |
+| `mjolnir --format codequality`                | تقرير GitLab Code Quality (عنصر لأداة طلب الدمج)             |
+| `mjolnir --strict`                            | يشغّل أيضًا قواعد مستوى quarantine (خطر FP أعلى)             |
 
 <details>
 <summary><strong>كل الأوامر الأخرى</strong> — فرز الاختبارات غير المستقرة، والتقارير، والحوكمة</summary>
@@ -452,18 +481,18 @@ mjolnir ci install
 أو أضف الـ action من Marketplace إلى workflow لديك بالفعل:
 
 ```yaml
-- uses: Sergey-Bar/Mjolnir@v1
+- uses: Sergey-Bar/Mjolnir@v3
   with:
     scope: changed
     fail-on: error
 ```
 
-ثبّت `@v1` لتتبع الخط الرئيسي، أو وسمًا دقيقًا (`@v0.5.32`) لبوابة قابلة لإعادة الإنتاج. يغطي [docs/DISTRIBUTION-KIT.md](docs/DISTRIBUTION-KIT.md) كلًّا من Marketplace وSmithery وسجلات MCP.
+ثبّت `@v3` لتتبع الخط الرئيسي، أو وسمًا دقيقًا (`@v0.5.32`) لبوابة قابلة لإعادة الإنتاج. يغطي [docs/DISTRIBUTION-KIT.md](docs/DISTRIBUTION-KIT.md) كلًّا من Marketplace وSmithery وسجلات MCP.
 
 لوضع النتائج في GitHub Code Scanning، ارفع SARIF (يتطلب `security-events: write` على مستوى الـ workflow أو الـ job):
 
 ```yaml
-- run: npx mjolnir-qa@latest --format sarif > mjolnir.sarif
+- run: npx mjolnir-qa@3.0.0 --format sarif > mjolnir.sarif
   continue-on-error: true
 - uses: github/codeql-action/upload-sarif@v3
   if: ${{ !cancelled() }}
@@ -476,7 +505,7 @@ mjolnir ci install
 ### إسناد النتائج إلى نطاق التغييرات
 
 ```bash
-npx mjolnir-qa@latest --scope changed
+npx mjolnir-qa@3.0.0 --scope changed
 ```
 
 تُسند النتائج إلى الأسطر التي أضافها فرعك، مقيسةً مقابل **merge-base**. النطاق هو مجموعة الملفات نفسها التي يكتشفها الفحص الكامل (ملفات spec لـ TS/JS وإعدادات المحوّلات، `test_*.py`، `*Test.java`، `*Tests.cs`، `.github/workflows/*.yml`)، إضافة إلى التغييرات غير المُثبتة وغير المتتبَّعة، لذا يعمل قبل أن تُجري commit. يُحدَّد الأساس بالترتيب `main → master → origin/main → origin/master → origin/HEAD`؛ ويمكنك تجاوزه بـ `--base <ref>`.
@@ -504,7 +533,7 @@ SCAN → EVIDENCE → HANDOFF → AGENT → RE-SCAN → PROOF
 أضفه إلى عميل يأتي مع CLI خاص به:
 
 ```bash
-claude mcp add mjolnir -- npx -y mjolnir-qa@latest mcp
+claude mcp add mjolnir -- npx -y mjolnir-qa@3.0.0 mcp
 ```
 
 أو إلى أي عميل يقبل كتلة `mcpServers`:
@@ -512,7 +541,7 @@ claude mcp add mjolnir -- npx -y mjolnir-qa@latest mcp
 ```json
 {
   "mcpServers": {
-    "mjolnir": { "command": "npx", "args": ["-y", "mjolnir-qa@latest", "mcp"] }
+    "mjolnir": { "command": "npx", "args": ["-y", "mjolnir-qa@3.0.0", "mcp"] }
   }
 }
 ```
@@ -603,7 +632,7 @@ mjolnir create-rule QA-PW-140 --title "Screenshot without diff bound"
 <img src="assets/readme/closing.svg" alt="شغّله على مستودعك." width="100%" />
 
 ```bash
-npx mjolnir-qa@latest
+npx mjolnir-qa@3.0.0
 ```
 
 [اقرأ الدليل](https://sergey-bar.github.io/Mjolnir/guide/getting-started) · [موقع التوثيق](https://sergey-bar.github.io/Mjolnir/) · [npm](https://www.npmjs.com/package/mjolnir-qa)