Skip to content

Canonical terminology ​

Mjölnir's surfaces speak one vocabulary. When the README, the site, the terminal output and the JSON report name the same concept, they use the same word — drift between surfaces is how trust erodes, so the dictionary below is enforced by CI.

one concept, one word; drift between surfaces is how trust erodes).

Status: canonical reference, hand-written. Frozen surfaces it names (verdict vocabulary, score bands, exit codes) are locked in docs/VERSIONING.md.

The canonical terms ​

TermDefinitionLives in
Worthiness ScoreThe 0–100 measurement of a suite's verification quality: score = 100 − min(100, rate × NORMALIZATION_K), rate = totalDeductions / (testDeclarations + 1). A measurement, not a contract — it can be gamed, and it says nothing about production readiness.docs/SCORING.md
VerdictThe contract-stable band word rendered next to the score: UNWORTHY / NEEDS WORK / WORTHY / FORGED (score 100 only). Property-locked in tests/scoring-precision.spec.ts.src/reporter/score-state.ts
Score BandThe numeric range behind a verdict: critical < 50 · warning 50–79 · trusted 80–99 · forged 100 · unmeasured null (no tests found — never faked to 100). One mapping, three consumers (terminal, badge, web) — deriveScoreState() is the single source of truth.src/reporter/score-state.ts
FindingOne thing a rule detected: severity (error/warning/info), location, message, fix, verify step. The unit of the report — never called "issue", "problem" or "violation".src/types.ts
Evidence Level (E0–E2)How the finding was detected: E2 deterministic proof (full deduction), E1 pattern evidence (half, rounded down), E0 observation only (zero deduction, advisory — reported, never gating).docs/SCORING.md
Trust Level (L0–L5)The overall trust a consumer can place in one finding, combining the static evidence ladder with runtime corroboration from a real run report: L0 observation only · L1 heuristic static · L2 deterministic static · L3 the finding's file executed · L4 the finding's test executed · L5 the run verdict corroborates the defect class. L3–L5 require runtime corroboration — a static-only finding can never claim them.src/types.ts
Measured FP RateThe false-positive rate of a rule measured against real OSS code: hand-classified verdicts, n ≥ 10, at the rule's current detectorRevision. Below the bar a rule ships on assumption — displayed as PROVISIONAL, never claimed as measured.docs/FP-AUDIT.md
TierA rule's shipping confidence class: core (default report, ≤ 10% measured FP), extended (default, ≤ 30% FP), quarantine (opt-in via --strict: > 30% FP or unmeasured). Omitted tiers resolve measurement-dependently — an unmeasured rule can never default into core.src/rules/rule.ts, docs/RULE-CAPABILITY-MATRIX.md
Verification RunA real test-run report (Playwright JSON, Jest JSON, Vitest JSON, JUnit XML) Mjölnir reads for runtime corroboration and forensics. Evidence, not truth — the report describes the run; it does not prove the suite is correct. Jest/Vitest reports carry one attempt per record (no per-attempt history), so TRUE-FLAKE never fires from them.src/types.ts
Re-runThe deterministic re-scan that proves a fix: mjolnir fix re-detects after each applied fix and shows the before/after. Proof comes from the re-run, not the fix.mjolnir fix --dry-run
BaselineA stored snapshot of the current finding set (.mjolnir/baseline.json) used as a comparison point so only new/worsened findings gate a PR. Pre-existing findings are not absolution — they remain in the full report. The baseline VERB is retired in the v6 carve; scan --scope changed compares against the merge-base instead.(retired — see docs/cli-contract.json)
DiffA fresh scan compared against a baseline: new/worsened only. Exit 1 says the PR should not merge. The diff VERB is retired in the v6 carve — scan --scope changed is the same comparison against the merge-base.mjolnir scan --scope changed
CI GateThe exit-status contract in CI: 0 clean · 1 findings at/above gate (or the diff verdict blocks) · 2 inconclusive — the analysis did not finish or the surface is unsupported, so a CI step should fail on it just as on 1 · 10 usage error · 20 internal error. Numbers frozen; 2 is not a pass.docs/VERSIONING.md
ReportAny machine-readable artifact: JSON (schemaVersion: 1, additive-only), SARIF 2.1, mermaid, the machine verification contract. No consumer may parse human-rendered text to learn semantics.docs/machine-contract.md
ForensicsRuntime evidence from a real run: retries, true flakes, durations, selector health (forensics, triage, pw-report, doctor:playwright). Distinguishes what a run shows from what a scan suspects.mjolnir help forensics
Detector RevisionThe implementation revision of a rule. Any detection-logic change increments it; a measurement recorded against a different revision is stale (PROVISIONAL) until re-measured.src/rules/rule.ts
Partial ScanA scan that ran but was truncated (time budget, unreadable input). Always exits 2 and carries a banner — a partial result is never presented as complete, and "no findings" on a partial scan means nothing.src/cli.ts

Spec → product mapping (locked decision D1) ​

The original 68-section product spec used "Trust Score" and "trust states" vocabulary. The product ships the terms below instead; the spec names are never used in product surfaces. This table is the resolution for every future "is it Trust Score or Worthiness Score?" question:

Spec termProduct termWhy
Trust ScoreWorthiness ScoreContract-stable, property-locked; renaming would break every consumer for zero user value
Trust states (untrusted / partial / trusted / verified)Score Bands + Verdicts (critical/warning/trusted/forged → UNWORTHY / NEEDS WORK / WORTHY / FORGED)Same semantics, contract-locked vocabulary
Issue / problem / violationFindingOne word for one concept across every surface
Bug Score— (no equivalent; do not invent)Score is a measurement, not a bug count

Anti-vocabulary (forbidden in product surfaces) ​

These are enforced by tests/contract/docs-consistency.spec.ts:

  • "trust score" — never; the score is the Worthiness Score.
  • "bug score" — never; the score is not a bug count.
  • "issue"/"issues" for findings — the GitHub-tracker senses ("open an issue", "issue template", "tracking issue") are fine; using the word for what a scan detected is not.

Archive and plan documents (docs/archive/, docs/tiers/, .kilo/) are exempt — they are historical records, not product surfaces.

Released under the MIT License.