Politica di Soppressione

"Una soppressione non è una cancellazione. È un'assunzione di responsabilità."

Il sistema di soppressione di Zenzic permette ai team di dichiarare eccezioni validate — deviazioni intenzionali che non sono difetti. È uno strumento di governance di precisione, non una via di fuga. Ogni soppressione viene registrata, verificata e costa punti nel Quality Score.

Livelli di Reporting — Semantica del Footer di Audit

Quando esegui zenzic check all o zenzic check all --audit, Zenzic emette un footer che riporta lo stato attuale delle soppressioni. Questo footer usa una tassonomia semantica con quattro distinti livelli di reporting:

Stato	Soppressioni	Etichetta	Severità	Significato
Clean State	0	(nessuna etichetta)	✅ Verde	Integrità totale — nessuna soppressione in uso. La documentazione è a baseline.
Managed Debt	0 < n ≤ CAP e CAP ≤ 30	`[MANAGED DEBT]` (cyan)	⏳ OK	Le soppressioni sono in uso entro il profilo di cap sovrano.
Extended Debt	0 < n ≤ CAP e CAP > 30	`[EXTENDED DEBT]` (giallo)	⚠️ Avviso	Le soppressioni sono in uso con un profilo di cap esteso e richiedono revisione di governance.
Cap Exceeded	n > CAP	`[CAP_EXCEEDED]` (rosso)	🚨 Errore	Le soppressioni superano il cap configurato. Il gate di CI fallisce con exit code 1 quando `suppression_cap_fail_hard=true`. La bonifica è obbligatoria.

# Clean state — zero soppressioni
🔒 Suppression Audit: 0/34 (inline: 0, per-file: 0)

# Managed debt — entro budget (25 su 34 soppressioni consentite)
🔒 Suppression Audit: 25/34 (inline: 25, per-file: 0) [MANAGED DEBT]

# Extended debt — al limite (34 su 34 soppressioni; limite raggiunto)
🔒 Suppression Audit: 34/34 (inline: 34, per-file: 0) [EXTENDED DEBT]

# Cap exceeded — oltre il limite (39 su 34; gate fallisce)
🔒 Suppression Audit: 39/34 (inline: 35, per-file: 4) [CAP_EXCEEDED] — EXIT CODE 1

Impostare il Budget di Soppressione

Il CAP è configurato in .zenzic.toml:

[governance]
suppression_cap = 34  # Massimo numero di soppressioni consentite prima del fallimento del gate

Se suppression_cap è omesso, Zenzic usa un default built-in di 30.

I Quattro Livelli di Soppressione

Zenzic offre quattro livelli di soppressione, dal più preciso al più ampio. Sono progettati per essere combinati: un progetto ben governato usa ciascun livello per il suo scopo specifico.

Livello	Meccanismo	Ambito	Audit Trail	Costo Score
1. Inline	Commento `<!-- zenzic:ignore: ZXXX -->`	Singola riga	✅ Sì	1 pt/soppressione
2. Per-file	`governance.per_file_ignores` nel TOML	Glob di file	✅ Sì	1 pt/voce
3. Exclusion Zone	`excluded_dirs` / `excluded_file_patterns`	Directory o pattern	❌ No	0 pt
4. Directory Policy	`governance.directory_policies` nel TOML	Glob di file	✅ Sì (audit mode)	0 pt

Le Exclusion Zone sono silenziose

I file nelle exclusion zone sono completamente invisibili a Zenzic. Non vengono emessi finding, non viene mantenuto nessun audit trail e non viene registrato alcun impatto sul punteggio. Usa le exclusion zone solo per asset genuinamente non documentali (output di build, file di terze parti). Per eccezioni intenzionali nella documentazione, usa il Livello 1 o il Livello 2 — mantengono vivo l'audit trail.

Livello 1 — Soppressione Inline

La soppressione più precisa: un commento, una riga, un finding.

File Markdown (.md):

Nome legacy mantenuto per accuratezza storica. <!-- zenzic:ignore: Z601 -->

File MDX (.mdx):

Nome legacy mantenuto per accuratezza storica. {/* zenzic:ignore: Z601 */}

Entrambe le forme di commento sono invisibili nell'output renderizzato. Usa la forma di commento coerente con lo stile del file circostante per mantenere gli esempi e il sorgente consistenti.

Per sopprimere più codici sulla stessa riga, aggiungi un commento per ogni codice:

Una riga. {/* zenzic:ignore: Z107 */} {/* zenzic:ignore: Z601 */}

Posizione Raccomandata: Trailing (In Coda)

Il commento dovrebbe trovarsi sempre alla fine della riga, seguendo la convenzione industriale stabilita da # noqa (Python), // eslint-disable-line (JavaScript) e // lint:ignore (Go).

- Riferimento storico — naming legacy mantenuto qui. <!-- zenzic:ignore: Z601 -->

Livello 2 — Soppressione Per-File

Silenzia una regola per un intero glob di file senza aggiungere commenti inline al sorgente. Usalo per le pagine in cui le eccezioni intenzionali sono strutturalmente necessarie (guide legacy, documentazione di migrazione).

Aggiungi una tabella [governance.per_file_ignores] al tuo .zenzic.toml:

[governance.per_file_ignores]
"docs/migration/**"  = ["Z601"]  # riferimenti brand intenzionali nel contesto di migrazione
"docs/legacy/*.md"   = ["Z101"]  # link rotti noti verso sistemi dismessi

La chiave della mappa è un glob relativo alla root del repository (corrispondente ai percorsi mostrati nell'output del CLI). Ogni voce nell'elenco è una soppressione, conteggiata nel totale del Technical Debt.

Usa zenzic explain per controllare lo stato

Esegui zenzic explain Z601 per vedere lo stato attuale della soppressione per-file di una regola — la tabella Config Genealogy mostrerà ogni glob pattern in cui la regola è silenziata.

Livello 3 — Exclusion Zone

Bypass totale: i percorsi nelle exclusion zone non vengono mai scansionati.

excluded_dirs          = ["legacy/", "third-party/"]
excluded_file_patterns = ["CHANGELOG*.md"]

Le exclusion zone non hanno nessun costo sul punteggio perché non sono soppressioni — sono confini di perimetro. Usale per:

Output di build e asset generati (build/, dist/)
Documentazione di terze parti inclusa così com'è
Changelog storici che contengono segreti di esempio e sintassi deprecata

Non usare le exclusion zone per nascondere il vero debito documentale.

Livello 4 — Directory Policy

Esenzioni strategiche a costo zero per interi rami di directory o glob di file specifici. Progettate per eccezioni strutturali dove le soppressioni sono giustificate organizzativamente, non come debito tecnico. A differenza delle exclusion zone, le directory policy mantengono un audit trail in modalità --audit.

Aggiungi una tabella [governance.directory_policies] al tuo .zenzic.toml:

[governance.directory_policies]
"docs/blog/**"                    = ["Z601"]  # post storici del blog — riferimenti ai codename attesi
"docs/explanation/registry.mdx" = ["Z601"]  # registro SSOT dei codename

La chiave della mappa è un pattern glob relativo alla root del repository (corrispondente ai percorsi mostrati nell'output del CLI). I finding corrispondenti vengono rimossi silenziosamente prima della visualizzazione con costo zero di suppression debt — non vengono mai conteggiati nel footer Suppression Audit.

Gerarchia: Directory Policy > Per-file ignore > Inline

Per scegliere il livello di soppressione:

Livello 4 per esenzioni strategiche ratificate organizzativamente che riguardano più file (es. intera directory blog/). Costo zero.
Livello 2 per eccezioni file per file con debito esplicito (1 pt/voce). Compare nel Suppression Audit.
Livello 1 per eccezioni ad-hoc a livello di riga nella prosa. 1 pt ciascuna. Massima visibilità nel sorgente.

Modalità Audit e Label `[POLICY_EXEMPTION]`

Quando si esegue zenzic check all --audit, le esenzioni di directory policy non vengono eliminate — emergono con un label [POLICY_EXEMPTION] preposto al messaggio del finding. Questo permette ai revisori di governance di ispezionare ciò che è strategicamente esente senza rompere l'invariante a costo zero:

$ zenzic check all --audit
explanation/brand-history.mdx:21 [Z601] [POLICY_EXEMPTION] Brand obsolescence: 'LegacyNameA'
explanation/brand-history.mdx:22 [Z601] [POLICY_EXEMPTION] Brand obsolescence: 'LegacyNameB'
blog/2026-05-24-log-v080.mdx:1 [Z601] [POLICY_EXEMPTION] Brand obsolescence: 'LegacyReleaseCodename'

I finding di sicurezza (Z201–Z204) bypassano sempre le directory policy incondizionatamente — non possono essere esentati indipendentemente da qualsiasi configurazione TOML.

Formula del Costo del Technical Debt

Le soppressioni attive (Livelli 1 e 2) riducono il quality score:

\text{debt} = n

Dove $n$ è il numero totale di soppressioni attive e cap è governance.suppression_cap (default: 30).

Soppressioni attive	Cap = 30	Debt	Punteggio finale (da 100)
0	30	0 pt	100
1	30	1 pt	99
10	30	10 pt	90
30	30	30 pt	70
31	30	31 pt	69
35	30	35 pt	65

Il debt viene applicato dopo il Gravity Cap. Se il tuo brand score è 0, il totale viene limitato a 70, e poi il debt viene sottratto da quel valore.

suppression_cap è una soglia di hard-fail di governance, non un moltiplicatore del debt. Superare il cap attiva l'exit code 1 indipendentemente dal gate di punteggio (fail_under).

Perché la soppressione costa punti?

Zenzic non può valutare la qualità di ciò che non può vedere. Ogni soppressione è un punto cieco. La formula del debt rende questo costo esplicito e visibile nel punteggio, invece di nasconderlo dietro un numero perfetto. Zenzic non valuta in curva.

Codici Sopprimibili vs Inviolabili

Zenzic divide i codici di finding in due classi: Sopprimibili (l'intenzione dell'autore è sovrana) e Inviolabili (i fatti di sicurezza non possono essere dichiarati falsi positivi).

Codice	Nome	Sopprimibile?
Z101	LINK_BROKEN	✅ Sì
Z102	ANCHOR_MISSING	✅ Sì
Z103	ORPHAN_LINK	✅ Sì
Z104	FILE_NOT_FOUND	✅ Sì
Z105	ABSOLUTE_PATH	✅ Sì
Z106	CIRCULAR_LINK	✅ Sì
Z107	CIRCULAR_ANCHOR	✅ Sì
Z201	CREDENTIAL_SECRET	🔒 Mai
Z202	PATH_TRAVERSAL	🔒 Mai
Z203	PATH_TRAVERSAL_FATAL	🔒 Mai
Z204	FORBIDDEN_TERM	🔒 Mai
Z301	DANGLING_REF	✅ Sì
Z302	DEAD_DEF	✅ Sì
Z303	DUPLICATE_DEF	✅ Sì
Z401	MISSING_DIRECTORY_INDEX	✅ Sì
Z402	ORPHAN_PAGE	✅ Sì
Z403	MISSING_ALT	✅ Sì
Z404	CONFIG_ASSET_MISSING	✅ Sì
Z501	PLACEHOLDER	✅ Sì
Z502	SHORT_CONTENT	✅ Sì
Z503	SNIPPET_ERROR	✅ Sì
Z505	UNTAGGED_CODE_BLOCK	✅ Sì
Z901	RULE_ENGINE_ERROR	✅ Sì
Z902	RULE_TIMEOUT	✅ Sì
Z405	UNUSED_ASSET	✅ Sì
Z406	NAV_CONTRACT	✅ Sì
Z601	BRAND_OBSOLESCENCE	✅ Sì

La Legge dell'Inviolabilità

zenzic:ignore: Z201, Z202, Z203 e Z204 vengono silenziosamente rifiutati. Il security gate opera indipendentemente dal motore di soppressione. Anche se un commento zenzic:ignore è presente, Zenzic emette comunque il finding ed esce con il codice 2 o 3.

Non puoi ignorare una breccia.

Bypass di Tutte le Soppressioni: `--audit`

Il flag --audit forza un sovereign audit completo: tutte le soppressioni attive — sia inline che per-file — vengono ignorate durante l'esecuzione del controllo. Ogni finding che sarebbe normalmente nascosto da un commento zenzic:ignore o da una voce per_file_ignores viene portato in superficie.

zenzic check all --audit

Usa --audit per:

Vedere lo stato reale della documentazione prima di un rilascio
Capire la portata del debt soppresso prima di alzare o abbassare il cap
Verificare che i finding soppressi siano ancora eccezioni intenzionali (e non regressioni)

Le exclusion zone (excluded_dirs, excluded_file_patterns) non vengono bypassate da --audit — definiscono il perimetro di scansione, non la politica di soppressione.

Interazione con la Modalità `--strict`

--strict e zenzic:ignore operano a livelli diversi della pipeline di analisi:

Rilevamento: Zenzic trova una violazione (es. Z402, severità warning).
Filtro di soppressione: Se zenzic:ignore: Z402 è presente, il finding viene rimosso.
Valutazione della severità: --strict promuove i warning sopravvissuti ad errori. Agisce solo sui finding che hanno superato il passo 2.

Stato del finding	`--strict`?	Exit code	Motivo
Warning presente	No	`0`	Tollerato di default
Warning presente	Sì	`1`	Promosso ad errore
Warning + `ignore`	No	`0`	Eccezione validata
Warning + `ignore`	Sì	`0`	L'intento vince sul rigore
Z201/Z202/Z203/Z204	Qualsiasi	`2` o `3`	Inviolabile

Quando Sopprimere vs Quando Correggere

Usa la soppressione per l'intento documentato, non per l'evasione:

Riferimenti storici al brand — Voci di CHANGELOG, guide di migrazione e documentazione storica possono legittimamente mantenere naming legacy del prodotto (Z601).
Link di navigazione ToC — I pattern [Sezione](#example-sezione) che potrebbero attivare Z107 in documenti lunghi sono intenzionali.
Pagine intenzionalmente brevi — Una pagina glossario può essere sotto la soglia di conteggio parole Z502 per design.

Non usare la soppressione per:

Nascondere un link veramente rotto invece di correggere il target.
Silenziare Z402 invece di aggiungere la pagina alla navigazione.
Bypassare Z201/Z204 per "documentare" una credenziale reale o un termine proibito.

Vedi Anche

Gestire il Technical Debt — Guida passo-passo per verificare e ridurre il suppression debt.
Algoritmo di Scoring — Come il suppression debt interagisce con il quality score completo.
Riferimento Codici di Finding — Catalogo completo di tutti i codici Zxxx con passaggi di rimedio.
Riferimento Configurazione — Riferimento completo della sezione governance.

Livelli di Reporting — Semantica del Footer di Audit​

Esempi di Footer​

Impostare il Budget di Soppressione​

I Quattro Livelli di Soppressione​

Livello 1 — Soppressione Inline​

Posizione Raccomandata: Trailing (In Coda)​

Livello 2 — Soppressione Per-File​

Livello 3 — Exclusion Zone​

Livello 4 — Directory Policy​

Modalità Audit e Label [POLICY_EXEMPTION]​

Formula del Costo del Technical Debt​

Codici Sopprimibili vs Inviolabili​

Bypass di Tutte le Soppressioni: --audit​

Interazione con la Modalità --strict​

Quando Sopprimere vs Quando Correggere​

Vedi Anche​