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

---

In this section

• Writing Plugin Rules — implement BaseRule subclasses, register

  them via entry_points, and satisfy the pickle / purity contract.

• Writing an Adapter — implement the BaseAdapter protocol

  to teach Zenzic about a new documentation engine.

• Example Projects — four self-contained runnable fixtures that

  demonstrate correct and incorrect Zenzic configurations.

• Governance Playbook: Troubleshooting and Invariants —

  Release A CAP policy, suppression rules, and Zenzic failure playbooks.

• Shared Sovereign Verification Model —

  Family-wide nox/just/CI contract: fail-closed core resolution and local == CI.

• Supply-Chain Assurance Profile —

  Immediate advanced assurance baseline with auditable controls and runbook commands.

---

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 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 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.