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 author is the final guarantor of the Mirror Law.

Adding a Dependency​

When adding a new third-party dependency to a Zenzic project:

  1. Verify license compatibility (must be Apache-2.0-compatible: MIT, BSD, Apache-2.0, LGPL-3.0, ISC). GPL and proprietary licenses are forbidden.
  2. Add the dependency details to the NOTICE file (name, URL, copyright holder, license identifier).
  3. Run uv run reuse lint to verify compliance.

Bilingual Parity (Symmetry Check)​

To verify that the filesystem structure of the English and Italian docs trees matches exactly (Symmetry Guardrail), run:

diff \
  <(find docs -name "*.mdx" | sed 's|^docs/||' | sort) \
  <(find i18n/it/docusaurus-plugin-content-docs/current \
      -name "*.mdx" | \
      sed 's|^i18n/it/docusaurus-plugin-content-docs/current/||' | sort)

For the developers site:

diff \
  <(find developers -name "*.mdx" | sed 's|^developers/||' | sort) \
  <(find i18n/it/docusaurus-plugin-content-docs-developers/current \
      -name "*.mdx" | \
      sed 's|^i18n/it/docusaurus-plugin-content-docs-developers/current/||' | sort)

Any output from these commands represents a structural asymmetry that will produce a 404 error on Docusaurus language switchers.

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:

Contributor Runbook (Local Setup)​

Two supported local setups for running verification:

  1. Sibling layout (recommended): Place the core repository as a sibling of your target repository:

    workspace/
      zenzic/
      zenzic-doc/
      zenzic-action/

    Then run:

    just verify

  2. Explicit override layout (custom path): If your core repository is in a different location, export ZENZIC_CORE_PATH when running verify:

    ZENZIC_CORE_PATH=/absolute/path/to/zenzic just verify

If verification reports a missing core path, treat it as a setup misconfiguration, not as a quality warning to suppress.

9) Adding a New ADR​

When a significant architectural decision is made — one that constrains future contributors or resolves a structural tension — it must be recorded:

  1. Create developers/explanation/adr-<slug>.mdx with the next available ADR number.
  2. Create the Italian mirror at the corresponding path in i18n/it/docusaurus-plugin-content-docs-developers/current/explanation/.
  3. Add both files to the index table in ADR Vault.
  4. Record the decision in the [ADR] section of the relevant repository governance log.

Per governance policy, ADR entries are append-only records. To amend a decision, add a new ADR that references the original and documents the amendment — never rewrite history.

10) Docusaurus Configuration Repairs​

When maintaining the Docusaurus configurations (e.g., docusaurus.config.ts), apply the following repair patterns to ensure locale-sovereign routing and cross-locale preference persistence.

Unifying dark mode storage namespace​

To prevent dark mode preference resetting when switching locales, disable namespace partitioning in the top-level configuration:

// docusaurus.config.ts
storage: {
  namespace: false,
},

To bypass the Docusaurus i18n link-rewrite pipeline and point directly to absolute global locations (like the blog), declare the navbar item using type: 'html':

// docusaurus.config.ts — blog navbar item example
{
  type: 'html',
  value: '<a class="navbar__item navbar__link" href="/blog">Blog</a>',
  position: 'left',
},

11) Converting Static SVGs to React Components​

When converting a static SVG carrying text or data nodes into a React component for MDX pages:

  1. Create a new component file src/components/<Name>.tsx using the same visual layout.
  2. Replace hardcoded text literals with <Translate id="..."> wrappers.
  3. Source dynamic numeric data (weights, codes, scores) from the canonical Python module via a generated JSON fixture instead of hardcoding attributes.
  4. Register the component in src/theme/MDXComponents.js to make it globally available in MDX.
  5. Delete the original .svg file from the repository.