Skip to main content

Developer Release and Governance Protocol

Use this guide as the default operational contract for every contribution in Zenzic repositories.

This is the execution protocol. ADRs remain the historical rationale layer.

Release A policy applies hard enforcement: no suppression debt beyond the CAP scan scope.

1) Four-Gate Hierarchy​

A change is Ready for release only when all four gates pass.

  1. IDE Gate

Fix lint and type issues while authoring.

  1. Pre-commit Gate

Commit is blocked on style, parsing, and local consistency failures.

  1. Pre-push Gate

Push is blocked by full project verification, including i18n parity and path/link security checks.

  1. CI/CD Gate

The same verification runs in shared infrastructure and must match local outcome.

Operational rule: do not bypass a failing gate by downgrading checks. Fix root cause or apply a narrowly-scoped and auditable exception.

2) Brand and Obsolescence Policy​

  • Strong enforcement baseline is active.
  • Legacy patterns are deprecated and must be detected by governance checks.
  • Transitional terminology is tolerated during the current migration window.

Practical effect:

  • New material should target stable enforcement terminology.
  • Legacy terminology may remain only where required by historical context.
  • Do not deprecate legacy terminology until a dedicated cleanup phase is completed, otherwise Z601 noise will flood the pipeline.

3) Namespace Contracts (Z4 and Z6)​

  • Z4 namespace: structural and infrastructure invariants.
  • Z6 namespace: governance and lifecycle policy invariants.

Mandatory rules:

  • Frozen code identities are immutable.
  • Reuse or semantic reassignment of frozen IDs is forbidden.
  • New governance behavior belongs in Z6.
  • Structural checks and platform invariants belong in Z4.

4) Contribution Checklist​

Before commit:

  • Run the repository standard local checks.
  • Confirm no unsanctioned config bypass was introduced.
  • Keep changes mirrored across EN and IT when parity applies.

Before push:

  • Run full verify entrypoint.
  • Confirm hook-driven execution paths and direct command paths produce the same result.

Before merge:

  • Ensure CI reproduces local pass state.
  • Remove temporary exclusions that are no longer justified.
  • No Core PR that alters documented behavior can be merged into the release branch without a corresponding merged PR in zenzic-doc. The Maintainer is the final guarantor of the Mirror Law.

5) Suppression Policy (Release A)​

  • CAP sovereign default is 30 active suppressions.
  • CAP is configurable per repository in [governance].suppression_cap.
  • Scope is global: inline comments plus per-file config suppressions.
  • Enforcement is fail-hard: if count is 31 or more, check all exits 1.
  • Every run prints the suppression counter in the report footer.

When configured CAP is higher than the sovereign default (> 30), the footer shows [EXTENDED DEBT] to make tolerance regimes explicit and auditable.

Expected footer format:

Suppression Audit: X/30

Canonical inline syntax:

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

6) Common Zenzic Blocks​

Z105 Path Safety Breach​

Symptom:

  • Zenzic blocks a relative traversal path and reports a path safety breach.

Standard resolution:

  • Prefer absolute site-root paths (for example /blog/post-slug) over multi-level relative traversals.

Validated exception:

  • Use inline suppression only when the bridge is reviewed and intentional.
{/* zenzic:ignore: Z105 - validated cross-locale bridge */}
[Read in Italian](/blog/it/article)

Z602 I18N Parity Drift​

Symptom:

  • CI fails because a base file has no locale mirror or required frontmatter parity fields are missing.

Resolution:

  • Create the mirror file in the locale tree.
  • Align required frontmatter fields (title, description by default).

Z602 is a contract check, not an optional lint preference.

7) Transition to Final Enforcement Standard​

This migration is a two-stage transition:

  1. Identity stage (current)

release_name is set to the stable identifier while legacy terminology remains tolerated historical wording.

  1. Hardening stage (planned)

After dedicated cleanup of legacy references, the historical terminology can be fully deprecated and strictly enforced by Z601.

This staging prevents false-positive saturation while preserving governance signal quality.

8) Shared Sovereign Verification Model (Family Repositories)​

The zenzic family repositories share one deterministic gate model for nox, just, and CI workflows:

  1. Explicit override: environment variable ZENZIC_CORE_PATH.
  2. CI canonical topology: ./_zenzic_core.
  3. Developer sibling topology: ../zenzic.
  4. Each candidate must contain src/zenzic.
  5. Fail-closed policy: PyPI fallback is prohibited in repository quality gates.

Operational consequences:

  • Local and CI are required to run the same verification entrypoint (just verify).
  • CI must checkout the core repository into _zenzic_core before verification.
  • Temporary config workarounds must not replace structural gate alignment.
  • Explicit branch override (ZENZIC_CORE_REF) is allowed only as a governed exception with mandatory metadata (ticket, reason, approver, expiry) and fail-closed enforcement.
  • Isolation checks must remain silent in tracked sources: contributor dogfooding uses local .zenzic.local.toml, while CI receives isolation parameters only through runtime environment injection.

Canonical reference: