Scoring Design

Design Rationale

The Zenzic Documentation Quality Score (DQS) is deliberately non-forgiving on Security and Governance. The algorithm encodes the principle that:

• A document set with leaked credentials is not a quality product at any score.
• A document set with uncontrolled brand decay cannot exceed 70/100, regardless of its link integrity.

Security violations produce an immediate score of 0, bypassing all other computation. Governance violations receive exponential amplification above 10 occurrences, and a full Governance-bucket wipe caps the total score at 70.

Dual-Gate Architecture

fail_under and suppression_cap operate as orthogonal constraints evaluated independently:

• Score gate: score < fail_under → zenzic score exits with code 1
• Governance cap: |Fₛ| > suppression_cap → zenzic score exits with code 1

A hybrid policy such as fail_under = 90, suppression_cap = 30 enforces: "Overall quality must never drop below 90/100, and regardless of score, no more than 30 suppressed defects are ever tolerated."

Because every suppression deducts 1 point (flat-cost model), the maximum achievable score for a repository is:

$\text{Max Achievable Score} = 100 - |F_s|$

where $|F_s|$ is the total active suppression count. Configuring fail_under > 100 - suppression_cap creates a mathematical contradiction. Safe rule: fail_under ≤ 100 - suppression_cap.

Worked Example

Scenario: A repository has 2 broken links (Z101), 3 orphan pages (Z402), 5 untagged code blocks (Z505), and 15 Z601 brand violations, with 8 active suppressions (cap = 30).

Stage 1 — Security Gate: No Z2xx findings → continue.

Stage 2 — Penalty Table:

Tier	Cap	Deduction	cat_pts
Structural	30	2 × 8.0 = 16.0	14.0
Navigation	25	3 × 4.0 = 12.0	13.0
Content	20	5 × 1.0 = 5.0	15.0
Governance	25	15 × 2.0 = 30.0 → cap to 25	0.0

$S_{\text{base}} = 14 + 13 + 15 + 0 = 42$

Stage 3 — Governance Escalation: 15 Z601 violations → $n_{\text{excess}} = 5$ → multiplier $= 2^{5/5} = 2.0$ → deduction $= 30 \times 2 = 60 \to \min(60, 25) = 25$. Brand bucket = 0.

Stage 4 — Gravity Cap: $\text{cat\_pts}_{\text{brand}} = 0$ → $S_{\text{gravity}} = \min(42, 70) = 42$.

Stage 5 — Suppression Debt: $n = 8$ suppressions → flat-cost: $\omega_{\text{debt}} = 8$.

$S_{\text{final}} = \max(0,\; 42 - 8) = \mathbf{34}$

Reading the CLI Output

Running zenzic score displays a Quality Breakdown Ledger that exposes every arithmetic step — from raw per-tier penalties to the applied cap, the Gravity Cap adjustment, suppression debt, and the final score.

✨ Quality Score: 65/100

╭─ Quality Breakdown ──────────────────────────────────────╮
│   Category     Issues  Weight  Raw Pts  Applied Pts      │
├──────────────────────────────────────────────────────────┤
│ ✓ structural      0      30%      0           0          │
│ ✓ navigation      0      25%      0           0          │
│ ✗ content         2      20%     -4          -4          │
│ ✗ brand          15      25%    -30         -25 (CAPPED) │
├──────────────────────────────────────────────────────────┤
│   Σ Subtotal                                71           │
╰──────────────────────────────────────────────────────────╯
  ! Technical Debt (6 suppressions)          -6 pts
  = Final Quality Score                      65 / 100

Column guide:

Column	Meaning
Raw Pts	Post-escalation deduction before the category cap, shown as a negative value (or 0).
Applied Pts	Deduction actually subtracted, capped at the tier maximum.
(CAPPED)	The raw deduction exceeded the tier cap and was truncated.
Σ Subtotal	Sum of all retained cat_pts values before Gravity Cap and Suppression Debt.

When the Gravity Cap fires (Brand bucket = 0), an extra line appears between Σ Subtotal and Technical Debt:

│   Σ Subtotal                                75           │
╰──────────────────────────────────────────────────────────╯
  ! Gravity Cap Enforcement (Brand = 0)       -5 pts
  ! Technical Debt (0 suppressions)            0 pts
  = Final Quality Score                       70 / 100

The arithmetic is always explicit: Σ Subtotal − Gravity Cap − Suppression Debt = Final Score.

Result Interpretation

Informational Findings

Informational findings are non-blocking diagnostics for visibility and observability:

• They do not reduce DQS.
• They never trigger the Security Override.
• In SARIF they are emitted at note level.

Typical examples: Z106 (CIRCULAR_LINK), Z114, Z906.

Label Semantics: [MANAGED DEBT] and [EXTENDED DEBT]

• [MANAGED DEBT]: active suppressions are present and the project remains on sovereign cap profile (suppression_cap <= 30).
• [EXTENDED DEBT]: active suppressions are present while using an expanded cap profile (suppression_cap > 30).

These labels describe governance posture and help reviewers track suppression growth over time.

Suppression Posture Inspection

zenzic score        # view current suppression posture in the Breakdown Ledger
zenzic check all --audit   # view all findings without active suppressions applied