Palimpsests

Repository on GitHub, which uses git. git is distributed.

The project maintains a good first issue label that marks starter tasks suitable for new or casual contributors — small, self-contained work such as documentation fixes, CLI polish, and additional test cases (the label and its initial set of tasks were curated on 2026-08-14). These tasks do not require adding core functionality, so they can be picked up by contributors who are not yet familiar with the codebase. They are discoverable as a filtered list of open issues carrying the label (see URL).
met_url:
https://github.com/Assault-Consulting/Palimpsests/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22

GitHub requires 2FA as of March 2023. [osps_ac_01_01]

Two-factor authentication for the project's maintainers is provided by a Time-based One-Time Password (TOTP) authenticator application, not SMS. TOTP is a cryptographic mechanism — an HMAC-based one-time code derived from a shared secret and the current time — so it does not carry the impersonation risk of unencrypted SMS-based 2FA. All maintainers with write/admin access to the central GitHub repository authenticate with app-based TOTP (and/or hardware security keys); none rely on SMS.

Code review requirements are documented in docs/REVIEW.md, with the contributor workflow in CONTRIBUTING.md and merge authority in GOVERNANCE.md. The document covers all three required elements. How review is conducted: every change — code and documentation — lands through a pull request that a non-author must approve before merge; main is branch-protected, so required green checks plus one non-author approval are enforced, not merely requested. What must be checked: the reviewer confirms that tests ship with behavior and that coverage stays above the gate (statement ≥ 90%, branch ≥ 80%), that ruff lint is clean, that any new dependency is justified, that security-sensitive paths (audit chain, key management, the crypto boundary, untrusted-input deserialization, the capability boundary) receive extra scrutiny against SECURITY.md / THREAT_MODEL.md / ASSURANCE-CASE.md, that public API/CLI and wire-format changes are deliberate and respect the format freeze, and that documentation matches the change; changes affecting released artifacts additionally require byte-verification and a green reproducible-build job. What is acceptable: approval means the reviewer believes the change is correct, tested, within the project's security and design boundaries, and free of known issues that would argue against inclusion — a reviewer who is unsure asks rather than approves, and author confidence alone is not grounds to merge.
met_url:
https://github.com/Assault-Consulting/Palimpsests/blob/main/docs/REVIEW.md

Every proposed modification to Palimpsests is reviewed by a non-author before release, which far exceeds the 50% threshold. main is branch-protected: direct pushes are blocked, and every change — code and documentation alike — must go through a pull request that receives at least one approval from a person other than the author, plus a green required status check (ci-complete: lint, tests, and coverage across macOS/Linux/Windows), before it can be merged. These protections have been enforced since 2026-07-11 (documented in GOVERNANCE.md), which is the measurement anchor for the review-coverage figure: every merge from that date forward is non-author reviewed, so the reviewed fraction is effectively 100% and monotonically rising. The requirement is documented in GOVERNANCE.md and CONTRIBUTING.md.

Palimpsests has a reproducible build, so this is Met rather than N/A: the project publishes distribution artifacts, and both the sdist (.tar.gz) and the wheel (.whl) are bit-for-bit reproducible — building the same commit produces identical bytes. Determinism is achieved by building with hatchling via PEP 517 (fixed archive-member order, no wall-clock build time stamped into output), pinning SOURCE_DATE_EPOCH to the commit date, and fixing LC_ALL=C.UTF-8, TZ=UTC, and umask 0022. This is enforced on every push and pull request by the reproducible-build job in .github/workflows/ci.yml, which runs scripts/check_reproducible_build.sh to build the artifacts twice and fail if they differ; the job is a required check in the ci-complete gate. The release workflow builds published artifacts with the same pinned SOURCE_DATE_EPOCH/locale/umask, so released files are the reproducible ones. A step-by-step reproduction recipe is documented (docs/REPRODUCIBLE-BUILD.md) so any third party can independently rebuild a release and verify it by hash. Reproducibility covers the Python distribution artifacts; the optional native (llama.cpp) path links against a separately installed C library and is out of scope.
https://github.com/Assault-Consulting/Palimpsests/blob/main/docs/REPRODUCIBLE-BUILD.md

The test suite is invoked in the standard way for Python: python -m pytest (equivalently pytest) from the repository root, with pytest configured in the standard [tool.pytest.ini_options] section of pyproject.toml. This is the conventional Python test invocation, documented in CONTRIBUTING.md and used unchanged by the CI workflow. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/pyproject.toml

The project uses continuous integration. On every push to main and every pull request, GitHub Actions runs the automated test suite (pytest) and the linter (ruff) across a matrix of three operating systems (Linux, macOS, Windows) and two Python versions (3.11, 3.12). New and changed code is integrated into main frequently via pull requests, with the tests run automatically on each. Branch protection requires the checks to pass before merge. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/.github/workflows/ci.yml

A FLOSS coverage tool exists for the selected language (coverage.py, run via pytest-cov), so N/A does not apply and the project meets the bar directly. The automated pytest suite achieves 90.3% statement coverage measured over the whole src/palimpsests package; only if TYPE_CHECKING: blocks and raise NotImplementedError lines are excluded, per the standard coverage convention. The single module that reads low — the in-process ctypes backend llamacpp_backend.py, which can only run with the optional [native] extra against a real GGUF model on GPU hardware and therefore cannot be exercised in CI — is counted, not omitted: the overall figure clears 90% with it included, and that backend is validated separately on hardware (benchmarks/RUNBOOK.md). Coverage is computed on every push and pull request (pytest --cov --cov-report=json) and enforced by scripts/coverage_gate.py, which fails the build below 90% statement (and 80% branch). The coverage job is a required check in the ci-complete gate, so coverage cannot silently regress below the bar.

A FLOSS coverage tool exists for the selected language (coverage.py, run via pytest-cov with branch coverage enabled), so N/A does not apply and the project meets the bar directly. The automated pytest suite achieves 82.4% branch coverage measured over the whole src/palimpsests package, with branch = true set in the coverage configuration; only if TYPE_CHECKING: blocks and raise NotImplementedError lines are excluded, per the standard convention. The hardware-only in-process ctypes backend llamacpp_backend.py — runnable only with the optional [native] extra against a real GGUF model on GPU hardware, so not exercisable in CI — is counted, not omitted: the overall figure clears 80% with it included, and that backend is validated separately on hardware (benchmarks/RUNBOOK.md). Branch coverage is computed on every push and pull request and enforced together with statement coverage by scripts/coverage_gate.py, which fails the build below 80% branch (and 90% statement). The coverage job is a required check in the ci-complete gate, so branch coverage cannot silently regress below the bar.