chock

The latest release line (0.1.x) is the supported version, stated in SECURITY.md's supported-versions table. The upgrade path is documented and deliberately predictable: CHANGELOG.md describes every release's changes, and the project's versioning contract makes upgrades safe to reason about — PATCH releases never change compiled output (enforced mechanically by a golden-file test suite), and MINOR releases document what changed. Upgrading is pip install --upgrade chock followed by chock sync, which recompiles the repo's artifacts deterministically.
https://github.com/open-coder-ai/chock/blob/main/CHANGELOG.md

GitHub Issues on the repository (https://github.com/open-coder-ai/chock/issues), with issue templates, labels (good first issue, roadmap; the catalog repo adds policy wanted), and all current issues triaged.

N/A: no vulnerability reports have been received or resolved in the last 12 months (the project's first public release was August 2026). The policy is already in place for when one arrives: SECURITY.md commits to crediting reporters unless they request otherwise.
https://github.com/open-coder-ai/chock/blob/main/SECURITY.md

SECURITY.md documents the full response process: reports come through GitHub private security advisories (with an explicit instruction not to open public issues for exploitable findings), what a report should include, acknowledgment within 7 days and initial assessment within 14 days, fixes shipped in a patch release, reporter credit unless anonymity is requested, and a new enforcement-matrix invariant (SEC-* entry) when the fix requires one.
https://github.com/open-coder-ai/chock/blob/main/SECURITY.md

Python is the sole implementation language. The coding style is defined by the Ruff configuration committed in pyproject.toml (lint ruleset + formatter, line length, target Python version), supplemented by the repository's coding rules in AGENTS.md. CONTRIBUTING.md requires contributions to pass these checks, and CI enforces them on every pull request.
https://github.com/open-coder-ai/chock/blob/main/pyproject.toml

Enforced automatically by Ruff (FLOSS): ruff check and ruff format --check run in CI on every pull request as part of the required validate jobs, and locally in the repository's own pre-commit conformance gate — a style violation fails the build rather than relying on reviewer attention.
https://github.com/open-coder-ai/chock/blob/main/.github/workflows/ci.yml

N/A: the project is pure Python and generates no native binaries; there is no compiler or linker invocation in the build.

N/A: pure Python — there is no compilation step that could strip debugging information; installed files are the source files themselves, and Python tracebacks retain full source context.

The project builds as a single Python package via the standard PEP 517 build backend (python -m build); there is no recursive sub-directory build, so no cross-dependency ordering problem can arise.

N/A: Python is used directly from source rather than compiled — the distribution is a pure-Python wheel containing the source files, with no build-time code generation. (Separately, the artifacts the tool itself generates into adopter repositories are deterministic and byte-identical across platforms and reruns, enforced by a golden-file test suite in CI, but that is the software's runtime behavior rather than a build step.)

Installation and uninstallation follow the standard Python packaging convention: pip install chock and pip uninstall chock. The package is published on PyPI, works in any virtualenv, and is also runnable without installation via pipx run chock. Uninstalling removes the tool cleanly; artifacts the tool wrote into an adopter's repository are ordinary committed files under the adopter's control.

Installation is delegated entirely to pip, which honors the standard Python installation conventions: virtual environments (VIRTUAL_ENV), --prefix, --root (the DESTDIR equivalent for Python packaging), --target, --user, and PIP_* environment variables. The project defines no custom installer and overrides none of these locations.

CONTRIBUTING.md opens with a numbered quick-setup block using standard Python conventions: clone, then pip install -e '.[dev]' (editable install with the dev extra, which brings in the full test and lint environment), followed by an explicit verification sequence the contributor runs to confirm the environment works — pytest -q, ruff check ., ruff format --check ., and the project's own conformance checks. No custom tooling or bespoke bootstrap script is required.
https://github.com/open-coder-ai/chock/blob/main/CONTRIBUTING.md

Runtime and development dependencies are declared in pyproject.toml in the standard PEP 621 computer-processable form (project.dependencies and project.optional-dependencies). CI and build dependencies are additionally pinned in compiled requirements files under requirements/ (generated by pip-compile), each carrying exact versions and sha256 hashes and installed with --require-hashes.
https://github.com/open-coder-ai/chock/blob/main/pyproject.toml

Dependabot is enabled on the repository for both security alerts and version updates (grouped into a single weekly PR to keep the update stream reviewable), so newly disclosed vulnerabilities in external dependencies surface automatically and are fixed by merging the update. GitHub secret scanning and CodeQL run alongside it. The project vendors no convenience copies of third-party code — every external dependency arrives via pip from the declared manifests — and CI installs are hash-pinned with --require-hashes, so a tampered or substituted dependency fails the build closed rather than installing silently.
https://github.com/open-coder-ai/chock/blob/main/.github/dependabot.yml

Both apply. The project uses the standard Python library wherever possible — notably, the vendored pre-tool-use adapter and gate runner that Chock writes into adopter repositories are stdlib-only by contract, so they carry no third-party surface at all. The remaining externally-maintained components are ordinary pip dependencies declared in pyproject.toml (and hash-pinned in requirements/ for CI), so identifying one is reading a single manifest and updating it is a version bump — which Dependabot proposes automatically.
https://github.com/open-coder-ai/chock/blob/main/pyproject.toml

The project targets Python 3.11+ and uses current standard-library APIs (e.g. pathlib, tomllib, importlib.resources, datetime with explicit timezones) rather than their deprecated predecessors. Deprecation warnings are treated as defects rather than noise: the test suite surfaces them and Ruff's lint ruleset flags outdated constructs in CI, so a deprecated call fails review rather than accumulating.

The full automated test suite (712 tests) runs in GitHub Actions on every push and every pull request to main, across Python 3.11 and 3.12, alongside an acceptance tier, a packaged-binary check, lint/format checks, and CodeQL. Results are reported as GitHub status checks on the commit and PR, and the core jobs are required checks under branch protection — a failing suite blocks the merge rather than merely reporting
https://github.com/open-coder-ai/chock/blob/main/.github/workflows/ci.yml

The project's practice is 100%, not 50%: every bug fix ships with a regression test in the same pull request, and CONTRIBUTING.md requires it. Recent examples each landed with a dedicated test module — the gate-runner bypass fixes (tests/test_gate_bypasses.py), manifest-id validation (tests/test_manifest_id_safety.py), coverage-honesty overclaims (tests/test_coverage_honesty*.py), Windows line-ending defects (tests/test_windows_line_endings.py), adopter-data-loss fixes (tests/test_adopter_safety.py), and the policy-id trailing-newline fix found by the property suite (tests/test_properties.py).
https://github.com/open-coder-ai/chock/tree/main/tests

Measured with coverage.py (FLOSS): 81% statement coverage across 712 tests. The measured figure understates actual coverage, because a substantial share of the CLI and hook code paths execute in subprocesses during the acceptance tier — coverage.py cannot attribute those lines to the parent run — and the installed hooks execute vendored copies of the source rather than the source files themselves. The test suite itself is FLOSS (pytest + Hypothesis), and coverage is reproducible locally with pytest --cov.

CONTRIBUTING.md states the policy in writing: behavior changes require tests in the same pull request, and the project's review standards name the test suite as non-negotiable for new functionality. It is enforced rather than aspirational — CI runs the full suite plus an acceptance tier on every pull request as required status checks, and the repository's own committed policies (agent-discipline) additionally block weakening or deleting assertions to make a change pass.
https://github.com/open-coder-ai/chock/blob/main/CONTRIBUTING.md

Documented in CONTRIBUTING.md, the instructions contributors are pointed at for change proposals: tests are expected for behavior changes, and required CI must pass before merge.

The linters run at strict settings repo-wide with no ignore-baseline; the one deliberately pinned choice (ruff minor version) exists to keep formatting deterministic in CI, not to relax rules. Beyond linting, the project holds itself to stricter-than-typical machine-enforced contracts: byte-identical compiled outputs across PATCH releases (golden suite) and a documented line-budget/style check on its own sources.

he design applies the standard principles where they bear on a repo-local governance tool. Least privilege: workflow tokens are read-only by default with write scopes granted per-job, and the tool requests no credentials of its own. Fail-safe defaults: gates fail closed — an unresolvable CI base ref exits non-zero rather than passing, the hook installer bakes an absolute interpreter path (a missing interpreter previously meant exit 127, which a host reads as "allow"), and empty or uninstalled surfaces claim nothing. Complete mediation: the CI gate re-checks the same compiled gates server-side, where local hook bypasses cannot reach. Input validation by allowlist: policy ids, manifests, agent selections, URL schemes, and catalog paths are all validated against fixed patterns or schemas. Economy of mechanism: one compiled gate definition drives every surface, so there is a single place to reason about behavior. Untrusted-input separation: repository and web content processed by the tool is treated as data, never as instructions. No dynamic code execution (eval/exec) exists anywhere in the codebase. The full argument, with the test suite proving each mechanism, is in docs/assurance-case.md.
https://github.com/open-coder-ai/chock/blob/main/docs/assurance-case.md