Skip to main content

Shared Sovereign Verification Model

This page defines the shared verification contract used across the zenzic family repositories (zenzic, zenzic-doc, zenzic-action).

The intent is operational determinism: local and CI must run the same logic against the same core semantics.

1) Why this model exists​

  • Prevent local/CI behavioral drift.
  • Prevent stale published-core execution in repository quality gates.
  • Keep contributor expectations explicit, auditable, and stable over time.

This model is mandatory for repository gates (not optional guidance).

2) Core Resolution Contract​

Resolution order is sovereign and deterministic:

  1. Explicit override: ZENZIC_CORE_PATH
  2. CI topology: ./_zenzic_core
  3. Sibling development topology: ../zenzic

Validation rule:

  • Every candidate path must contain src/zenzic.

Fail-closed rule:

  • If no candidate is valid, verification stops with an explicit error.
  • PyPI fallback is prohibited in repository quality gates.

3) CI Topology Contract​

CI workflows must:

  1. Resolve branch parity against the core repository (target branch first, fallback to main only when target branch does not exist in core).
  2. Checkout core to ./_zenzic_core.
  3. Run the same verification entrypoint used locally (just verify).

Recommended explicitness:

  • Export ZENZIC_CORE_PATH=_zenzic_core in the verify step environment.
  • For repositories with non-homonymous branch naming, set ZENZIC_CORE_REF as an explicit CI override.
  • Governed override metadata is mandatory when ZENZIC_CORE_REF is used: ZENZIC_CORE_REF_TICKET, ZENZIC_CORE_REF_REASON, ZENZIC_CORE_REF_APPROVER, ZENZIC_CORE_REF_EXPIRES_ON.
  • Fail-closed applies to every override path: missing metadata, malformed expiry date, expired override, or non-existent branch in core must stop CI.

4) Layer Responsibilities​

LayerRequired behaviorNon-negotiable invariant
justfilePrimary operator entrypoint (check, verify)Uses sovereign resolution order and fail-closed stop
noxfile.pyDeterministic automation wrapper for sessionsUses the same sovereign order as justfile
.github/workflows/*.ymlShared execution topologyChecks out _zenzic_core before running verify
release-contracts recipeDrift guardRejects PyPI fallback patterns and auto-tagging in release paths

5) Contributor Runbook​

Two supported local setups:

  1. Sibling layout (recommended)
workspace/
  zenzic/
  zenzic-doc/
  zenzic-action/

Run:

just verify
  1. Explicit override layout (custom path)
ZENZIC_CORE_PATH=/absolute/path/to/zenzic just verify

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

6) Anti-Drift Policy​

The following are prohibited in repository quality gates:

  • uvx zenzic@... fallback as a substitute for local core semantics.
  • Temporary config workarounds used to mask core-version drift.
  • Divergent local and CI verification entrypoints.

Temporary compatibility shims are allowed only as short-lived transitions and must be removed once structural parity is restored.