Scoring Algorithm¶

The Zenzic Documentation Quality Score (DQS) is a deterministic, 0–100 integer computed from the findings of every active check. Given the same repository state, the algorithm always produces the exact same score.

For conceptual model, CLI output interpretation, and worked examples, see Scoring System.

Architecture Overview¶

The scoring pipeline operates across five sequential stages:

1. Security Gate    → Z2xx finding? score = 0, early return.
2. Penalty Table    → per-code deductions, per-tier caps.
3. Governance Esc.  → exponential amplification if Z6xx > 10.
4. Gravity Cap      → brand score = 0 ⟹ total ≤ 70.
5. Suppression Debt → subtract ω_debt from capped total.

Stage 1 — Security Override¶

Before any category calculation, the engine evaluates Z2xx findings:

where \(\mathcal{S} = \{Z201, Z202, Z203, Z204, Z205\}\).

This is an unconditional early return — no flags, no configuration options, and no suppressions can bypass it. The five codes in \(\mathcal{S}\) represent binary failure conditions:

When the Security Override fires, ScoreReport returns security_override=True and security_findings=N (total Z2xx count).

Stage 2 — Weight Matrix & Penalty Table¶

If no Z2xx finding is detected, the engine calculates per-category scores using the 5-Tier Weight Matrix:

Zenzic Weight Matrix (5-Tier)¶

Category Penalty Formula¶

For each category bucket \(i\):

5. Finding Penalty Matrix¶

Every finding code is assigned a base penalty points value. Penalties are deducted from the respective category score during DQS evaluation.

Stage 3 — Governance Escalation¶

When Governance & Brand findings (codes \(\mathcal{G} = \{Z601, Z603, Z610, Z611, Z612, Z613, Z614, Z615, Z616, Z620\}\)) exceed 10 total occurrences, an exponential penalty amplifier is applied to the Governance category deduction:

where \(n_{\text{excess}} = \sum_{c \in \mathcal{G}} n_c - 10\).

Stage 4 — Gravity Cap¶

If the Governance bucket is fully zeroed (\(\text{cat\_pts}_{\text{brand}} = 0\)):

A document repository with unaddressed governance failures cannot score above 70/100.

Stage 5 — Suppression Debt¶

Under the flat-cost model, every active inline or per-file suppression deducts exactly 1 point:

where \(n\) is the total count of active suppressions (<!-- zenzic:ignore --> and per_file_ignores entries).

The final score is:

See Also¶

• Scoring System — DQS conceptual model, CLI breakdown, and worked example.
• Suppression Policy — Suppression posture levels and debt limits.
• Finding Codes — Full reference encyclopedia of all Z-codes.
• Configuration Reference — .zenzic.toml options and policy-as-code controls.