Skip to main content

CI & Delivery Governance

This document is the canonical statement of three laws that prevent recurring drift between repositories, CI enforcement, orchestration, and the public website:

  1. CI Law — how correctness is enforced per repository class.
  2. Maestro Law — what the internal orchestrator may and may not do.
  3. Website Delivery Law — which state transitions count as truth for the public website.

Where this document and any single repository's practice disagree, the repository practice must be brought into conformance or this document must be updated deliberately. Silence is not conformance.

1. Repository Classes​

Every repository in the estate is classified into exactly one lifecycle class. The machine-readable classification manifest and its publication contract are owned by zen-mgmt (CI governance authority). This section records the law; zen-mgmt records the data.

ClassMeaning
ACTIVE_PRODUCTShipping product code under active development.
ACTIVE_FOUNDATIONShared foundation (SDKs, protocols, persistence) consumed by active products.
ACTIVE_TOOLINGInternal tooling and harnesses in active use.
FROZEN_DONORContent frozen as a source for extraction; no new development.
SUPERSEDEDReplaced by a successor; kept for history and redirect targets.
ARCHIVERead-only history.

Classification may change only through a deliberate governance decision, never implicitly through inactivity or convenience.

2. CI Law​

Public / OSS repositories​

  • .github CI and Security workflows are required transparency and community surfaces. They must not be deleted to make problems disappear.
  • Every canonical check must also be reproducible repo-natively (a local command, bounded script, or equivalent) so a contributor can verify the same gates without GitHub.
  • GitHub-only opaque validation is forbidden: no security or correctness logic may exist only inside workflow YAML where local contributors cannot execute it.
  • Long-lived red public CI is operational drift. It must be root-caused and fixed, or explicitly classified (for example: blocked solely on a credential or owner input, with everything else green-ready). A permanently red public check is a trust-surface failure, not background noise.

Private repositories​

  • Git hooks are the canonical synchronous enforcement surface. Required checks execute locally, immediately, for the actor, at commit and/or push.
  • Private correctness must not depend on GitHub Actions quota, runner availability, or third-party runtime.
  • An unexpected .github directory appearing in a private repository is classified by policy before it is accepted; it is never blindly adopted as an enforcement surface.

Reference embodiment (this repository)​

This docs repository is the reference implementation of the private-repo law:

  • .githooks/pre-commit — fast, deterministic, offline checks on every commit.
  • .githooks/pre-push — the full validation suite (including production build) before every push.
  • scripts/validation/guard-no-github-actions.sh — fails if .github or GitHub Actions syntax is (re)introduced.
  • scripts/install-git-hooks.sh — installs the hooks via git config core.hooksPath .githooks; hooks are committed so every clone carries them.

The hooks layer locally reproduces validation that previously ran in GitHub Actions.

3. Maestro Law​

Maestro is the internal orchestration layer. Its authority is bounded:

  • Maestro orchestrates canonical gates; it does not define them. Gates are defined by repos (hooks, native commands, workflow configs) and by zen-mgmt policy.
  • Maestro does not replace public OSS transparency. Public .github CI remains the community-facing trust surface even where Maestro also executes the same checks.
  • Maestro may reconcile long-running red public CI: schedule, diagnose, and drive fixes for public checks that have been red beyond policy tolerance.
  • Private repository execution consumes the hook / repo-native gates; it does not substitute a parallel, weaker definition of correctness.

4. Website Delivery Law​

For the public website (zen-mesh.io) the following distinctions are law. They exist because each historical incident in this area came from collapsing one state into another.

LawMeaning
source correct != production currentA fix merged in the website or docs source changes nothing visible until a production deployment carries it.
deploy accepted != live verifiedA deployment being "Ready" is not proof the production URL serves the intended content. Live verification is a separate, required step.
Mon is the live observation authorityThe monitoring lane (zen-mon) owns independent observation of the live site.
Maestro reconcilesMaestro drives source, deployment, and observation states back into agreement when they drift.
Support qualifies deploymentThe deployment lane owns build/deploy execution and its acceptance receipts.
zen-mgmt owns policyRepository classification, gate profiles, and governance manifests are owned by zen-mgmt, not re-declared per repo.

A practical consequence for this repository: these docs are composed into the production website at website build time. A docs change here becomes publicly visible only after the website deployment lane ships a build that includes it. Docs merges are "source correct"; they are not "production current".

5. Status Anchors​

  • UNKNOWN observation status is never treated as HEALTHY.
  • A green local gate run and a green remote status are distinct facts; either alone is not conformance.
  • Historical evidence documents (including those under docs/80-EVIDENCE/) record what was true when written; they are never retroactively edited to match current law.