snodo

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

Development happens continuously on the public main branch, not only at release
points. Every change lands as an individual commit visible at
https://github.com/snodo-dev/snodo/commits/main, with agent and human work merged as
reviewable units between releases. Releases are tags on that history
(https://github.com/snodo-dev/snodo/releases), so the full interim state between any
two releases is available for review.

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

Each release carries a unique semantic version, set in pyproject.toml, published to
PyPI (https://pypi.org/project/snodo/) and tagged in git. A release gate
(scripts/check_release_version.py) runs in make release and in the release
workflow, and refuses to publish unless the git tag, the pyproject.toml version and
a matching CHANGELOG section all agree.

Every release is an annotated git tag of the form vX.Y.Z, created by the release
process and pushed with the release commit. Tags are listed at
https://github.com/snodo-dev/snodo/tags and each has a corresponding GitHub Release
carrying the changelog body and the built distribution artifacts.

Non-trivial release notes file in repository: https://github.com/snodo-dev/snodo/blob/main/CHANGELOG.md.

No CVE or equivalent has ever been assigned against snodo itself, so no release notes have had a vulnerability to identify. The criterion excludes dependencies; dependency advisories are handled separately by pip-audit and OpenSSF Scorecard in CI, and dependency upgrades that clear advisories are recorded in CHANGELOG.md.

Non-trivial SECURITY[.md] file found file in repository: https://github.com/snodo-dev/snodo/blob/main/SECURITY.md. [osps_do_02_01]

GitHub Issues: https://github.com/snodo-dev/snodo/issues

All bug reports are triaged and responded to. 170 issues have been closed against 10 open at time of writing, and issues are referenced by the commits that fix them (Fixes #N), so every report has a traceable response.

Enhancement requests are triaged in the same tracker as bug reports and receive the same response rate; the project is single-maintainer with a low volume of external requests, all of which have been answered.

https://github.com/snodo-dev/snodo/issues?q=is%3Aissue — the full issue history,
open and closed, is public and searchable, along with all responses.

https://github.com/snodo-dev/snodo/blob/main/SECURITY.md publishes the reporting
process, and it is linked from the README badge row on the project site.

https://github.com/snodo-dev/snodo/blob/main/SECURITY.md states that vulnerabilities
must not be reported as public GitHub issues, and gives a private reporting channel:
email security@snodo.dev, with the requested contents (description and impact,
reproduction steps, suggested fix). It commits to acknowledgement within 72 hours and
a fix within 14 days of a confirmed vulnerability.

No vulnerability reports have been received in the last 6 months, so there is no response time to report. SECURITY.md commits to acknowledgement within 72 hours, well inside the 14-day requirement.

Non-trivial build file in repository: https://github.com/snodo-dev/snodo/blob/main/Makefile.

Non-trivial build file in repository: https://github.com/snodo-dev/snodo/blob/main/Makefile.

snodo is pure Python. The build backend is hatchling and the workspace/dependency
manager is uv, both FLOSS. Test and lint tooling (pytest, ruff, import-linter,
hypothesis) is FLOSS. No proprietary tool is needed to build, test or release:
https://github.com/snodo-dev/snodo/blob/main/pyproject.toml

The project has an automated test suite (pytest, with hypothesis for property-based
tests) covering unit, integration and end-to-end levels. Instructions for running it
are in CONTRIBUTING.md under "Testing and checks":
https://github.com/snodo-dev/snodo/blob/main/CONTRIBUTING.md
Tests live in https://github.com/snodo-dev/snodo/tree/main/tests

The suite is invoked in the standard Python way: uv run pytest tests/
(end-to-end subset: uv run pytest tests/e2e/ -m e2e). The same command is used
locally and in CI: https://github.com/snodo-dev/snodo/blob/main/.github/workflows/ci.yml

Statement coverage is ~78%, enforced by a 75% minimum gate in CI. Coverage is
concentrated on the protocol engine and its invariants; the invariants INV1-INV5 are
additionally covered by property-based tests using hypothesis rather than by
example-based tests alone.

GitHub Actions runs the full test suite, ruff, and import-linter contract checks on
every push and pull request:
https://github.com/snodo-dev/snodo/blob/main/.github/workflows/ci.yml

CONTRIBUTING.md states the policy under "Testing and checks" and in the pull
request checklist: "Tests required for new behaviour" and "All existing tests must
pass, including e2e". Change classes carry specific requirements: a change to a
merge gate must add a test that injects the violation the gate exists to catch, and
a change touching tokens or invariants must extend the INV1-INV5 property suite in
tests/properties/test_invariants.py rather than adding only unit tests.
https://github.com/snodo-dev/snodo/blob/main/CONTRIBUTING.md

Recent feature work ships with its tests in the same commit. Examples: the ADR 040
"coder observes declared test runner" work, the worktree-isolation enforcement
(ADR 024/025), and the audit-log resolution fix on the merge path each added tests
alongside the change. The change log and commit history show the pattern:
https://github.com/snodo-dev/snodo/commits/main

The requirement is written into the pull request checklist in CONTRIBUTING.md
("Tests required for new behaviour"), which is the instruction document for change
proposals: https://github.com/snodo-dev/snodo/blob/main/CONTRIBUTING.md

ruff is run over the whole repository (uv run ruff check .) in CI on every push
and pull request. The rule set is pinned and explicitly enumerated in pyproject.toml
[tool.ruff.lint]: ruff's default F + E4/E7/E9 set, plus B904 and a flake8-bandit
subset (S105, S110, S311, S314, S602, S603, S607) added deliberately, each after its
existing violations were cleared. import-linter additionally enforces six
architectural layering contracts.
https://github.com/snodo-dev/snodo/blob/main/pyproject.toml

ruff, import-linter and the test suite are blocking checks in CI, so warnings are
fixed before merge rather than accumulating. Rules are added one at a time with
their violations fixed in the same release. Where a bandit finding is intentional it
carries a scoped # noqa with a written reason rather than a blanket suppression;
test and experiment trees ignore the bandit subset only, since those rules describe
a shipped binary's threat model and not a test harness.

All enabled lint findings are blocking in CI — there is no warning tier that is
tolerated. Strictness is ratcheted rather than maximal-by-default: the ruff rule set
is pinned and widened one rule at a time, each added only after its existing
violations are cleared, because an unpinned ruff bump would take the repo from clean
to thousands of findings with no code change and no way to tell a real regression
from a rule-set change. Intentional exceptions carry a scoped # noqa with a written
reason rather than a blanket suppression. import-linter additionally enforces six
architectural layering contracts as hard failures.
https://github.com/snodo-dev/snodo/blob/main/pyproject.toml

The primary developer designs the system around least privilege, containment and
tamper-evidence rather than trust. Concrete evidence in the codebase: agent coders
run inside per-task git worktrees with enforced containment (ADR 024/025); tool
access is a declared, whitelisted capability set per protocol mode rather than
ambient authority (ADR 035); the audit log is a SHA-256 hash chain so tampering is
detectable; human adjudication records are RS256-signed JWTs with the algorithm
pinned and the signing key held only by the CLI adjudicate path, with a separate
verify-only issuer that structurally cannot mint. Security-relevant design decisions
are recorded as ADRs with their rationale:
https://github.com/snodo-dev/snodo/tree/main/docs/decisions

The relevant error classes for this kind of software — a tool that executes untrusted model output — are command injection, path traversal / sandbox escape, privilege escalation via ambient credentials, secret leakage into logs, and tampering with the integrity record. Each has a counter in the codebase: subprocess invocation is argv-list only with no shell and a whitelisted binary; file and execution scope is bounded to the task worktree; capability grants are declared per mode and denied by default; the audit chain is hash-linked so retroactive edits are detectable; adjudication tokens moved from HS256 to RS256 with the algorithm pinned at verify time so an attacker cannot downgrade the signature scheme. The relevant bandit rules (S602/S603/S607/S105/S110/S311/S314) are enabled in ruff and enforced in CI, with each intentional exception carrying a scoped noqa and a written reason.