Development Contract

All commands run with this directory as the repository root. Code, tests, documentation, workflows, and artifacts remain project local; external Python libraries are consumed only through the generated locks.

Run make format while editing and make check before handoff. A concrete, testable unit is exercised as soon as it is implemented, and its documentation is updated in the same change. Do not defer all debugging or documentation to the end of a larger change.

Dependency or lock changes are incomplete until make licenses passes across all five installed lock environments. This is a fail-closed policy check, not a printable inventory: a new license or a changed exact exception must be reviewed locally before relying on the pull-request Dependency Review job.

After the locked development environment is prepared, make package builds both wheel and source archive without build isolation or network access. It installs the wheel into a clean target and runs the declared console entry point from that artifact, outside the source directory. The gate also proves that an operational console launch resolves the marked parent of the active project venv, never the artifact's site-packages path. Editable imports alone are never packaging evidence.

make docs-audit prepares the dedicated generated-lock environment, renders the documentation, and audits the output. Environment preparation may download locked wheels; rendering and auditing make no network requests. Broken local routes, anchors, canonical URLs, sitemap entries, robots.txt, llms.txt, symlinks, or non-deterministic timestamps are blocking failures at the same stage as the documentation change.

make standalone smoke-standalone uses a separate generated lock to build the native Linux executable for the host architecture. Verification binds its ELF identity, exact input digest, dependency lock, and generated bytes; smoke runs the binary outside the source tree with hostile import state and verifies its executable-directory local boundary. The amd64 and arm64 CI jobs are the release artifact producers.

Unit tests use strict process fakes and no real identity. Container build contexts and runtime payloads travel through the validated tar pipe only. Never add a bind mount, named volume, or podman cp. Every runtime container uses the bounded --userns=auto:size=2048 mapping; unbounded auto, keep-id, nomap, and host modes are rejected before container creation.