Passa al contenuto principale

Protocollo Operativo di Rilascio e Governance

Usa questa guida come contratto operativo predefinito per ogni contributo nei repository Zenzic.

Questa è la procedura di esecuzione. Gli ADR restano il livello storico di motivazione architetturale.

La policy Release A è enforcement di release: nessun debito di soppressione oltre il perimetro CAP.

1) Gerarchia dei Quattro Gate​

Una modifica è Ready for Release solo quando tutti e quattro i gate sono verdi.

  1. Gate IDE

Correggere lint e type issue durante la fase di authoring.

  1. Gate Pre-commit

Il commit viene bloccato in caso di violazioni stile, parsing o coerenza locale.

  1. Gate Pre-push

Il push viene bloccato dalla verifica completa di progetto, inclusa parità i18n e controlli di sicurezza path/link.

  1. Gate CI/CD

La stessa verifica gira in infrastruttura condivisa e deve replicare l'esito locale.

Regola operativa: non aggirare un gate fallito abbassando i controlli. Correggere la causa radice o applicare un'eccezione stretta, motivata e tracciabile.

2) Policy Brand e Obsolescenza​

  • Il codename della release attiva è definito in release_name del .zenzic.toml.
  • I codename precedenti sono elencati in brand_obsolescence e intercettati dai check Z601.
  • Il nuovo materiale deve usare terminologia agnostica rispetto alla versione.
  • I riferimenti storici ai codename restano solo dove necessari per cronologia.

3) Contratti di Namespace (Z4 e Z6)​

  • Namespace Z4: invarianti strutturali e infrastrutturali.
  • Namespace Z6: invarianti di governance e ciclo di vita.

Regole obbligatorie:

  • Le identità codice congelate sono immutabili.
  • Il riuso o la riassegnazione semantica di ID frozen è vietato.
  • Nuovi comportamenti di governance appartengono a Z6.
  • Check strutturali e invarianti di piattaforma appartengono a Z4.

4) Checklist Contributiva​

Prima del commit:

  • Eseguire i check locali standard del repository.
  • Verificare che non siano stati introdotti bypass di configurazione non autorizzati.
  • Mantenere i mirror EN/IT quando la parità è prevista.

Prima del push:

  • Eseguire l'entrypoint di verifica completa.
  • Confermare che percorsi hook e comandi diretti producano lo stesso risultato.

Prima del merge:

  • Verificare che la CI replichi il pass locale.
  • Rimuovere esclusioni temporanee non più giustificate.
  • Nessuna PR sul Core che altera il comportamento documentato può essere fusa nel branch di rilascio senza una corrispondente PR fusa in zenzic-doc. Il Maintainer è il garante finale della Mirror Law.

5) Policy Soppressioni (Release A)​

  • CAP sovrano di default a 30 soppressioni attive.
  • CAP configurabile per repository in [governance].suppression_cap.
  • Scope globale: commenti inline + soppressioni per-file in config.
  • Enforcement fail-hard: da 31 in su, check all termina con exit 1.
  • Ogni esecuzione stampa il contatore soppressioni nel footer del report.

Quando il CAP configurato e superiore al default sovrano (> 30), il footer mostra [EXTENDED DEBT] per rendere esplicito e auditabile il regime di tolleranza estesa.

Formato atteso del footer:

Suppression Audit: X/30

Sintassi inline canonica:

  • Markdown: <!-- zenzic:ignore: Z601 - historical reference -->
  • MDX: {/* zenzic:ignore: Z601 - historical reference */}

6) Blocchi Zenzic più comuni​

Z105 Path Safety Breach​

Sintomo:

  • Zenzic blocca un percorso relativo con risalita e segnala violazione di sicurezza path.

Risoluzione standard:

  • Preferire path assoluti dalla root sito (ad esempio /blog/slug-articolo) al posto di traversal relativi multi-livello.

Eccezione validata:

  • Usare soppressione inline solo quando il bridge è revisionato e intenzionale.
{/* zenzic:ignore: Z105 - cross-locale bridge validato */}
[Leggi in Italiano](/blog/it/articolo)

Z602 I18N Parity Drift​

Sintomo:

  • La CI fallisce perché un file base non ha mirror locale o manca la parità dei campi frontmatter richiesti.

Risoluzione:

  • Creare il file speculare nella tree locale.
  • Allineare i campi frontmatter richiesti (title, description di default).

Z602 è un check di contratto, non una preferenza opzionale di lint.

7) Hardening della Governance​

Il ciclo di hardening segue una transizione a due stadi:

  1. Stadio identità (corrente)

release_name è attivo con il codename corrente. I codename precedenti entrano in brand_obsolescence alla release successiva.

  1. Stadio hardening (pianificato)

Dopo una bonifica storica dedicata, i codename precedenti vengono promossi a obsolescenza con enforcement Z601 pieno.

Questa sequenza evita saturazione di falsi positivi preservando la qualità del segnale di governance.

8) Modello Sovrano di Verifica Condiviso (Repository della Famiglia)​

I repository della famiglia zenzic condividono un solo modello deterministico per nox, just e workflow CI:

  1. Override esplicito: variabile d'ambiente ZENZIC_CORE_PATH.
  2. Topologia canonica CI: ./_zenzic_core.
  3. Topologia sibling per sviluppo: ../zenzic.
  4. Ogni candidato deve contenere src/zenzic.
  5. Policy fail-closed: il fallback a PyPI e proibito nei quality gate del repository.

Conseguenze operative:

  • Locale e CI devono eseguire lo stesso entrypoint di verifica (just verify).
  • La CI deve fare checkout del core in _zenzic_core prima della verifica.
  • I workaround temporanei di configurazione non devono sostituire l'allineamento strutturale dei gate.
  • L'override esplicito di branch (ZENZIC_CORE_REF) e consentito solo come eccezione governata con metadati obbligatori (ticket, reason, approver, expiry) ed enforcement fail-closed.
  • I controlli di isolamento devono rimanere silenti nei file tracciati: il dogfooding contributor usa .zenzic.local.toml, mentre in CI i parametri di isolamento sono forniti solo tramite iniezione runtime di variabili d'ambiente.

Riferimento canonico: