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:

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