mjolnir-qa 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -11,6 +11,89 @@ once shipped, so this file is the record of what changed between versions.
 
 ## [Unreleased]
 
+## [2.1.0] — 2026-09-24
+
+### Added
+
+- Added seven milestone commands to the public CLI and root help:
+  - `mjolnir ci-integrity` validates GitHub/GitLab/Jenkins scan gates and reports non-blocking or disabled candidates.
+  - `mjolnir framework-maturity` reports bounded F0–F5 maturity while preserving human calibration authority.
+  - `mjolnir suppression-gate` evaluates reasons, expiry, allowlists, total counts, and matched-finding mass suppression.
+  - `mjolnir cross-file` reports duplicate test names, shared imports, circular dependencies, and amplified findings.
+  - `mjolnir contract-verify` validates machine-contract fields and binds persisted contracts to a fresh scan.
+  - `mjolnir trust-trend` persists, deduplicates, and compares trust snapshots.
+  - `mjolnir evidence-graph` builds provenance-bearing evidence graphs and supports file/rule queries.
+- Added a zero-touch PR framework: Conventional Commit enforcement, seeded property tests, merge-result verification, and local/CI command-parity checks.
+- Added dedicated, discoverable property and fuzz suites. Fuzz cases use fixed seeds; property tests remain isolated from default coverage collection.
+- Added CI integrity, suppression, contract, provenance, cross-file, and trust regression suites covering malformed input, partial scans, inactive suppressions, and platform-stable exit behavior.
+- Added stable-only `v1`/`v2` action-tag maintenance. RC tags never move stable consumer tags.
+- Added pinned current corpus revisions and local fixture tree revisions. Baseline counts were not rewritten; corpus drift remains an explicit audit failure.
+
+### Fixed
+
+- Fixed false-green milestone engines:
+  - machine-contract verification now compares every contract projection, including optional provenance and forensic verdicts;
+  - trust snapshots use caller-provided timestamps instead of an embedded wall clock;
+  - suppression mass uses actual matched pre-suppression findings and active suppressions;
+  - evidence provenance is derived from real file contents;
+  - cross-file dependency analysis uses the requested target root;
+  - framework maturity uses the supported F5 ceiling.
+- Fixed persisted contract handling: documents use strict runtime schema validation and are verified against a fresh scan rather than self-attesting.
+- Fixed zero-finding and partial-scan reporting so incomplete or unclassified analysis cannot render as a clean, proven, or merge-ready suite.
+- Fixed CI workflow audit parsing to fail closed for dynamic conditions, `continue-on-error`, negated commands, multi-pipe status masking, inactive GitLab rules, advisory `after_script` commands, and missing blocking scans.
+- Fixed the coverage job/ratchet mismatch: merge verification now generates the coverage summary it enforces.
+- Fixed stress determinism by normalizing both analysis and machine-contract duration fields, running real concurrent scans, and making the 10k workflow validate JSON even when findings are advisory.
+- Fixed property/fuzz discovery and workflow trigger/name so required PR checks are actually produced.
+- Fixed root help, command registry, README, and release documentation drift for the new command surface.
+
+### Security
+
+- The composite Action and generated CI surfaces use exact released versions, immutable action references, least-privilege permissions, and explicit exit semantics.
+- The composite Action defaults to blocking on findings and partial scans; advisory behavior requires an explicit opt-out.
+- Release publication is isolated from `main`, uses audited artifacts, npm OIDC trusted publishing with provenance, npm 11.5.1+, a `next` RC dist-tag, and verified GitHub prerelease assets.
+- Pull-request shell inputs and workflow-derived values are passed through environment variables instead of direct `${{ }}` interpolation.
+- Machine-contract, suppression-policy, roadmap, and persisted-artifact validation now reject malformed and adversarial inputs rather than fabricating or trusting them.
+- Main-branch deletion and the complete required PR check matrix are enforced by repository ruleset `01`. The repository is solo-maintained, so the owner explicitly chose not to require a second approving review.
+
+### Performance
+
+- Centralized deterministic CLI timing normalization and expanded replay, soak, and concurrent stress coverage.
+- Added bounded corpus scans, exact source revisions, and fail-closed baseline provenance checks.
+- Added practical pipeline/command regression tests without changing the frozen 96% branch ratchet.
+
+### Testing
+
+- Full instrumented release gate: 408 test files, 10,351 passing tests, one expected failure documenting the outstanding orphan corpus baseline, and five intentional skips.
+- Coverage ratchet at release: 98.58% statements, 96.00% branches, 99.38% functions, and 98.84% lines.
+- Focused gates green: build, lint, typecheck, certification, property, fuzz, stress/soak/concurrency, release/workflow contract tests, pack audit, brand, site, and local/CI parity.
+- Historical failed runs remain historical evidence; they are not retroactively changed.
+
+### Changed
+
+- `ci-local` now runs one complete instrumented suite plus property/fuzz/ratchet/audit/brand/site/parity gates instead of silently omitting release checks.
+- Release promotion is explicit and branch/tag based; merging the version PR does not itself publish npm.
+- Suppression counts and governance outputs distinguish configured, active, expired, and matched findings.
+- Rule IDs remain immutable across the 2.x line. Existing detector contracts,
+  including `QA-PW-001`, retain their identity while framework maturity and
+  evidence quality improve around them.
+- The CLI command registry is shared by help, dispatch, and CI-integrity classification.
+
+### Breaking changes
+
+- The package now requires Node.js `>=22.18`.
+- Direct composite-Action consumers now get blocking defaults for findings and partial scans unless they explicitly opt out.
+- Generated CI installation remains opt-in/advisory for first adoption; use `mjolnir ci install --gate error` when an enforcing install is required.
+- Stable release publication no longer occurs automatically from `main`; use the protected release branch and release workflow.
+- The historical `v2.0.3` tag is retained unchanged. This release does not move, delete, or republish that tag.
+
+### Migration
+
+1. Install or invoke `mjolnir-qa@2.1.0` with Node.js 22.18 or newer.
+2. Replace floating Action versions with `@v2` or the exact `v2.1.0` tag when reproducible enforcement is required.
+3. Review suppression expiry/allowlist policy before enabling `suppression-gate`; existing entries are policy data, not proof of human validation.
+4. Run the seven new commands in report mode first and review their JSON before making them release gates.
+5. Adjudicate remaining corpus count/orphan drift and human/design-partner validation separately; this release does not claim those are closed.
+
 ## [2.0.2] — 2026-09-22
 
 ### Fixed

package/README.md

@@ -150,6 +150,17 @@ 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`.
 
@@ -197,30 +208,26 @@ Three steps to trust your release pipeline:
 2. **Block in CI** — `npx mjolnir-qa@latest --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
 
-Add it to your pipeline so it gates releases on error findings:
+Install the advisory PR workflow first, so existing trust debt cannot break
+CI on day one:
 
 ```bash
-npx mjolnir-qa@latest --scope changed --blocking error
+mjolnir ci install
 ```
 
-`mjolnir ci install` writes the GitHub Actions workflow with a blocking gate (error severity), pinned to this version:
+After reviewing the findings or baselining existing debt, opt into blocking:
 
 ```bash
 mjolnir ci install --gate error
 ```
 
-Run advisory mode only when you want to preview findings without blocking:
-
-```bash
-mjolnir ci install --gate advisory
-```
-
 | 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 --gate error`   | Write the blocking PR workflow                  |
+| `mjolnir ci install`                | Write the advisory PR workflow (default)        |
+| `mjolnir ci install --gate error`   | Opt into the blocking PR workflow               |
 | `mjolnir business-case`             | ROI estimate: projected savings per finding     |
 | `mjolnir explain QA-CI-001`         | What, why and fix, plus the measured FP rate    |
 | `mjolnir why src/a.spec.ts:42`      | Why this exact line was flagged. Never gates.   |
@@ -236,30 +243,37 @@ mjolnir ci install --gate advisory
 
 <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 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           |
+| 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.
@@ -556,22 +570,20 @@ 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 the PR workflow with a blocking gate (error severity) — this is the
-default for a reason: findings that survive your pipeline survive your release.
+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 --gate error
+mjolnir ci install
 ```
 
-The gate is pinned to this version — a new release must not change your gate
-semantics without a commit of yours. Switch to advisory only when you want
-to preview findings without blocking:
+After reviewing existing debt, opt into an enforcing gate:
 
 ```bash
-mjolnir ci install --gate advisory
+mjolnir ci install --gate error
 ```
 
-In your existing workflow, pin the action and gate on error severity:
+In your existing workflow, pin the action and explicitly opt into an error gate:
 
 ```yaml
 - uses: Sergey-Bar/Mjolnir@4a588bc62d517bc85fc44c0eae64c6587d3bf70b0
@@ -634,11 +646,11 @@ 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` and `diff` become 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.       |
+| 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:
 

package/dist/cli.d.mts

@@ -1226,6 +1226,8 @@ interface ScanHooks {
    * never on the stdout machine contracts.
    */
   onGateNotice?: (notice: string) => void;
+  onTestFilesDiscovered?: (files: readonly string[]) => void;
+  onPreSuppressionFindings?: (findings: readonly Finding[]) => void;
 }
 /**
  * Workspace fallback for targets with no discoverable project root
@@ -1381,7 +1383,7 @@ declare function runScan$1(args: CliArgs, hooks?: ScanHooks): Promise<ScanResult
  * scripts/sync-sarif-version.cjs and guarded by the version-consistency
  * spec. cli.ts re-exports this as CLI_VERSION.
  */
-declare const ENGINE_VERSION = "2.0.2";
+declare const ENGINE_VERSION = "2.1.0";
 //#endregion
 //#region src/cli-io.d.ts
 /**
@@ -1623,7 +1625,7 @@ export declare function runAnalyzeCommand(argv: string[], io: {
 export declare function runCiAdapterCommand(argv: string[], io: {
   out: Output;
   err: Output;
-}): Promise<number>;
+}): number;
 //#endregion
 //#region src/commands/dashboard.d.ts
 export declare function runDashboardCommand(argv: string[], io: {
@@ -1643,6 +1645,36 @@ export declare function runMaturityCommand(argv: string[], io: {
   err: Output;
 }): number;
 //#endregion
+//#region src/commands/milestone.d.ts
+export declare function runFrameworkMaturityCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+export declare function runSuppressionGateCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): Promise<number>;
+export declare function runCrossFileCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): Promise<number>;
+export declare function runContractVerifyCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): Promise<number>;
+export declare function runTrustTrendCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): Promise<number>;
+export declare function runEvidenceGraphCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): Promise<number>;
+export declare function runCIIntegrityCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): Promise<number>;
+//#endregion
 //#region src/cli.d.ts
 export declare const runScan: typeof runScan$1, buildUniversalRules: typeof buildUniversalRules$1, fallbackWorkspace: typeof fallbackWorkspace$1, pathMatchesGlob: typeof pathMatchesGlob$1, isValidFindingRecord: typeof isValidFindingRecord$1, discoverAndParseRuntimeReport: typeof discoverAndParseRuntimeReport$1, KNOWN_RULE_IDS: ReadonlySet<string>, OVERLAP_META_BY_RULE_ID: ReadonlyMap<string, OverlapMeta>, EVIDENCE_OVERRIDES: ReadonlyMap<string, string>, SUITE_INVALIDATING_RULE_IDS: ReadonlySet<string>;
 /** A usage-error detail: the offending token, when one exists. */
@@ -1695,7 +1727,7 @@ export declare function runSuppressions(io?: {
   out: Output;
   err?: Output;
 }): number;
-export declare function printUsage(print: (s: string) => void): void;
+export declare function printUsage(print: (s: string) => void, width?: number): void;
 export declare function main(argv?: string[], io?: {
   out: Output;
   err: Output;