Developer Guide

Welcome to the Zenzic engineering community. We build tools that bridge the gap between human documentation and executable truth. Our codebase follows rigorous standards for performance, type safety (mypy --strict), and accessibility.

This section covers everything you need to extend, adapt, or contribute to Zenzic.

Operational governance and release troubleshooting start here:

• Governance Playbook: Troubleshooting and Invariants
• Shared Sovereign Verification Model
• Supply-Chain Assurance Profile

---

Core Engineering Guides

• Writing Plugin Rules

  ---

  Implement BaseRule subclasses, satisfy the pickle purity contract, and register entry-points.

  Read Guide

• Writing an Adapter

  ---

  Implement the BaseAdapter protocol to teach Zenzic about a new documentation engine topology.

  Read Guide

• Example Projects

  ---

  Four self-contained runnable fixtures demonstrating correct and incorrect Zenzic configurations.

  Explore Fixtures

• Governance Playbook

  ---

  Release CAP policies, suppression rules, and failure troubleshooting playbooks.

  Read Playbook

• Sovereign Verification Model

  ---

  Fail-closed core resolution, zero-network quality gate, and complete local-to-CI parity.

  Read Model

• Supply-Chain Assurance

  ---

  Auditable supply-chain controls, security baselines, and verification runbook commands.

  View Profile

---

Interactive Workflow with Just

Zenzic uses just as its interactive command runner. just is the fast day-to-day layer; nox is the reproducible CI layer underneath.

Command	Description
just sync	Install / update all dependency groups (uv sync --all-groups)
just check	Self-lint — run Zenzic on its own documentation (strict)
just test	Run the test suite (delegates to nox -s tests, Hypothesis dev profile)
just test-full	Run the test suite with Hypothesis ci profile (500 examples)
just verify	Pre-push gate: lint-all + build + verify-codes + strict audit + score stamp + freshness check
just build	Build the documentation site (fast, no strict enforcement)
just build-prod	Build the documentation site (strict mode, mirrors CI)
just serve [port]	Start the live-reload documentation server (default port 8000)
just clean	Remove generated artefacts (site/, dist/, .hypothesis/, caches, score file)

The Zenzic self-linting duty — just check — is the first command to run after any documentation change. Run just verify before every push to main.

Hypothesis profiles

Property-based tests use [Hypothesis](https://hypothesis.readthedocs.io/) with three profiles, controlled by the `HYPOTHESIS_PROFILE` environment variable: | Profile | Examples per test | When to use | |:--------|------------------:|:------------| | **dev** (default) | 50 | Day-to-day development (`just test`) | | **ci** | 500 | CI pipelines and `just test-full` | | **purity** | 1 000 | Pre-release exhaustive validation |

just test                          # dev profile (fast)
just test-full                     # ci profile (thorough)
HYPOTHESIS_PROFILE=purity just test  # pre-release

Mutation testing

Use `nox -s mutation` to run [mutmut](https://mutmut.readthedocs.io/) against `src/zenzic/core/rules.py`. This is deliberately **not** part of `just verify` — run it manually after working on the rule engine:

nox -s mutation

---

Contributing

Full contribution guidelines, code conventions, Core Laws, and the pre-PR checklist are in CONTRIBUTING.md on GitHub.

When you open a pull request, GitHub automatically loads the PR checklist — verify all items before requesting a review.