Repository navigation
Releases
greenproof 0.5.0
Install: uvx greenproof@0.5.0 --version or pipx install greenproof==0.5.0 (PyPI).
Milestone M6 (SPEC section 15): six more agents on the hook protocol. All six are
experimental: the files follow each vendor's documentation as read on 2026-11-12 and none has
completed a real-CLI block-and-release run yet. Real payloads were captured from Claude Code
2.1.322 (no timestamp key, which the Copilot rule below relies on) and Antigravity CLI 1.0.8,
which sends terminationReason: "NO_TOOL_CALL" for a normal stop where its documents say
model_stop; both values run the gate.
Added
check --hookandsession-start --hookacceptcopilot,qwen,droid,antigravity,
openhandsandauggie. Each reads its CLI's own payload (session id, start directory, and
where there is one the field that marks a stop that is not the model finishing, which is
skipped) and answers in that CLI's output format; the same state, replay and release rules apply.init --agentswrites the hook files for them:.github/hooks/greenproof.json,
.qwen/settings.json,.factory/hooks.json,.agents/hooks.json,.openhands/hooks.json
and.augment/settings.json. Merging, ownership and exit 4 on an unusable file work as for
the other agents. Timeouts use each CLI's unit: seconds for Qwen (capped at 999, because Qwen
reads 1000 or more as milliseconds), Droid, Antigravity and OpenHands,timeoutSecfor
Copilot, milliseconds for Auggie. Droid's file is keyed directly by event name, and
Antigravity's greenproof entry is the keygreenproof.- Experimental adapters print a warning when named, and Qwen Code and Droid print a note about
approving or reviewing the hooks.--agents autonever installs an experimental adapter. It
now also detects Copilot (.github/hooks/or.github/copilot-instructions.md), Qwen
(.qwen/) and Droid (.factory/), but only for an adapter that is not experimental, so
none of them is picked yet. scripts/e2e/capture_payload.py, a hook command that appends its stdin, arguments and the
*_PROJECT_DIRand*_SESSION_IDenvironment variables to the file named by
GREENPROOF_CAPTURE, for recording real payloads before an adapter is marked supported. It is
not part of the wheel.- README: the agents that have no hook that can block a stop (Cline, Roo Code, Windsurf, Zed,
Warp, Aider, Continue, Kiro, Devin, Jules), which rely on AGENTS.md and CI, and Goose, Junie,
Amp and Kilo Code as planned.
Changed
- Under
--hook claude, a payload with atimestampkey is Copilot's (Copilot CLI and VS Code
also run the hooks in.claude/settings.json, and treat exit 2 from a stop hook as a
warning). When a.github/hooks/*.jsonfile holds a greenproof--hook copilotentry for the
event, the Claude hook defers: exit 0, no output, no state written. Otherwise it answers in
Copilot's format. hooks.pykeeps one table of per-agent protocols instead of per-agent branches; the output
for Claude Code, Cursor, Codex CLI, Gemini CLI and OpenCode is unchanged.inittakes the
notes and warnings it prints from attributes of each adapter module.- README: the Gemini CLI row points to Antigravity CLI, its successor.
Full changelog: v0.4.1...v0.5.0
greenproof 0.4.1
Install: uvx greenproof@0.4.1 --version or pipx install greenproof==0.4.1 (PyPI).
Fixed
initno longer writes hooks that point at an ephemeral environment. Run as
uvx greenproof init(orpipx run, or from a project venv that is only active in the
current shell), it found its own copy ofgreenproofon PATH and wrote the bare command into
the hook files; the agent's PATH does not have that copy, so the hook failed open. The
scripts directory of a virtual environment the running interpreter is in is now skipped when
looking for an installedgreenproof; apipx installoruv tool installsymlink in
~/.local/binstill counts. When none is found the hooks useuvx greenproof@Xas before,
and the summary says so and how to install it.- The AGENTS.md section named the command to run as bare
greenproof checkwhenever
--hook-commandwas not given, even when the hooks useduvx greenproof@X. It now names the
command the hooks use. - The workflow written by
init --ci githubinstalled nothing for a plain-pip Python project
(a pyproject,setup.pyorsetup.cfgwithoutrequirements.txt) or for npm without a
lockfile, sopython -m pytestran without pytest or the package, andnpm testwithout
node_modules. When the policy has nosetupcommand it now adds apython -m pip install
step (the package with itstest,tests,testingordevextra, the requirements files
for development and test, and the pytest, ruff, mypy or pyright the policy runs) and an
npm installstep. The step is in the workflow only:setupalso runs in--isolate
worktrees, wherepip install -e .would point your own environment at a temporary directory.
For a project with asrc/directory the run step also setsPYTHONPATH: src, so the revert
check's base worktree imports its ownsrc/and not the editable install of the checkout.
Changed
- Documentation only, no behaviour beyond the fixes above. README and SPEC describe the new hook
command rule, the AGENTS.md command and the CI install step,PYTHONPATH: srcincluded, and
thatinitadds an@AGENTS.mdimport to an existingCLAUDE.md. They also correct the
smoke key rule (some keys but not all is a policy error, exit 4), the OpenCode timeouts
(3600 s for the check, 120 s for session start), the claim that a Pythonparametrizefold
is blocked when its body ignores the row values (it warns), wheresetupruns (ci mode,
--isolateand revert worktrees), and theopencodechoices of--agentsand--hook.
The README quick-start output is re-run on 0.4.1. - README notes that a uv
exclude-newersetting keepsuvx greenproof@Xfrom resolving for
new releases, souvxhooks fail open until the release ages past the window. - SPEC marks each item of "Known limits (0.3.0)" as closed, narrowed or still open in 0.4.0.
MEASUREMENTS labels the 0.2.0 real-history section and marks the false blocks 0.4.0 no
longer blocks.
Full changelog: v0.4.0...v0.4.1
greenproof 0.4.0
Install: uvx greenproof@0.4.0 --version or pipx install greenproof==0.4.0 (PyPI).
Measured against 0.3.1 on the same inputs (MEASUREMENTS.md): of 744 tamper probes, 693 block
and 51 warn, and none passes (0.3.1: 687, 50 and 7); of 502 honest probes, 18 block that should
not (0.3.1: 35). On real history, 66 of 698 test-touching commits block (0.3.1: 75), 12 of them
false blocks (0.3.1: 21).
Added
tests.weakened: aforloop over a literal list or tuple, and aparametrizeover a
module-level name bound once to one, are compared by their distinct rows. Fewer distinct rows
than at the base blocks ("table rows reduced from N to M"), unless every base row is still
among the candidate's rows or the rows of new tests. A loop whose check no longer reads its
row blocks, and so does a table name that is bound again or changed in place
(CASES.append(4)). A table that cannot be read (passed to a call, built byrange) warns,
"table rows could not be read", and only when the base's table could be read.tests.weakened: rows count in the check total. A literal loop unrolled into fewer explicit
asserts blocks,assert all(<check> for x in <table>)counts one assert per row, repeated
rows count once ([1, 1, 1]is one case), and an assertion in a nesteddefthat nothing
calls does not count.tests.weakened: an expected value replaced by a matcher is a loose check on the other side
of==orassertEqual.assert f(1) == 2becomingassert f(1) == ANYblocks ("exact
check onf(1)loosened tof(1) == ANY"). Matchers read:ANYandmock.ANY, dirty-equals,
callee, testfixturesComparison, a class whose only base isobjectand whose own__eq__
never reads its second parameter, and a function whose every return is such a value (to
depth 3). Only the top-level operand is judged.tests.weakened:pytest.approxwith a tolerance that is a name or cannot be resolved is
read as loosened. A name bound to a module-level number is resolved first.tests.weakened: a same-file helper earns credit for its asserts only when it is unique at
module level, plain (not async, a generator or decorated) and straight (no branch, loop,
early return,raise,yield,await, skip or exit;with raises/warns/subTestis
allowed). Assertions behind anifor after areturnare not credited, so a check moved
into such a helper blocks.tests.weakened: a loop over a literal table whose body can leave the row outside its
with self.subTest(...)block (break,continue,return,raise, a skip) counts only
its first row, since later rows may never run.tests.skipped: a test file moved or renamed onto a livecollect_ignoreor
collect_ignore_globentry of aconftest.pyblocks. Every write to the list is read, not
only the first assignment.runner.tampered: a deleted root Makefile is followed, and a target that was in it and is
gone blocks.-iinMAKEFLAGSorMFLAGS, and.IGNOREbare or naming the target, block.
A command substitution in a check's arguments warns. Anincludeof a$(wildcard ...)glob
that matches tracked files is read; an include that the Makefile itself rebuilds warns.runner.tampered: nox commands held in a name bound once, or returned by one same-file
helper, are read, and a helper's literal arguments are bound. A name set throughglobals(),
exec,setattror a star import is unknown and warns.runner.tampered: a policy script that no longer runs a kind of check its base ran blocks,
even when other lines remain (pytestandruff check .becomingruff check .): "it no
longer runspytest". The scripts it calls are read into it, to depth 4, 64 files per side
and 1 MiB per file. The lint kinds are one kind, and a call that cannot be read leaves the
script unjudged by kind. A script that a recipe of the base Makefile runs counts as run by the
policy command that runs the target.runner.tamperedandci.tampered: npm-w/--workspaceis package selection.npm test
ornpm test --workspacesbecomingnpm test -w webblocks ("npm ran every package before
and now onlyweb"), and widening passes. In a workflow step the selection is the step's own
(the words before--), and the roottestscript is no longer read in place of the package
the step selects.ci.tampered: where errexit is off, a subshell or group around a check that ends in another
command (( pytest; echo done )) swallows the check, and so does one withexit 0,
return 0ortrap ... EXIT(orERR).( pytest )alone is honest, and so is
( pytest; exit 0 )underset -e. A GitHubrun:step runs with errexit on, so these
apply to scripts and other CI files that run without it.ci.tampered: acp,install,lnorrsyncinto the test tree blocks when it lands on a
test file, on a file that decides the runner, or on a tracked file it would overwrite. It
warns for a new non-test file. A copy with several sources or a computed destination is not
read.ci.tampered:nx run-manybecomingnx affected, ornx affectedadded to a monorepo
test step, warns (0.3.0 did this inrunner.tamperedonly).- The release workflow publishes the OpenCode plugin to npm as
opencode-greenproofafter PyPI
accepts the release, with npm trusted publishing from thenpmenvironment: no token is
stored, and a tag that does not match the package's version fails before anything is
published.
Changed
tests.removed: a test renamed while its body was edited is paired with its old self when
the match is unique and the bodies share most of their tokens (0.6 in the same file, 0.75
across files; a body of at least 10 tokens). Repeated leaf names are told apart by the
trailing parts of the qualified name, and names equal once case and punctuation are ignored
are paired. A paired test goes through the weakening comparison, so a rename that also drops
a check blocks astests.weakened. Below the thresholds, or on a tie, it stays a removal and
blocks.tests.skipped: acollect_ignoreentry that hides only non-test files is no longer a skip.tests.weakened:pytest.approxwith the default tolerance, or a literalrelorabsof
1e-6 or less, counts as a pinned value, and so does a value built by a class imported from
outside the test tree (QueryParams('a=1')). A class defined in the test tree earns no
credit.tests.weakened(Go): a drop in the line count of checks warns instead of blocking when the
credited count is at least the base's and every number or string literal of the removed
checks is still present ("by line; helper checks or table rows give N against M"). The
credit is a helper's checks that run on every path, and a loop over a literal table of
distinct rows times the loop's live checks that read the row. A row that is only assigned to
_, printed or logged is not read. Rust and JS loops that replace separate checks still
block.tests.skipped(Go): a conditionalt.Skipthat only new table rows reach is excused only
inside at.Runclosure, on a field the checks never read, and only when every base row is
still present and unchanged.- The line-level flow reader for Go, Rust and JS also reads Rust
let ... else, labelled
breakandcontinue,goto, andswitchfallthrough when deciding whether a check runs. runner.tampered: more than 32 different pytest runs (was 8) are needed before the runs are
no longer compared one by one.runner.tampered: a package-filter rename or glob (webtoapp-*) passes when it still
selects every package the old filter selected, read from thepackage.jsonnames in the
tree, and warns when it does not.runner.tampered: a masked check line in a recipe (-pytest,|| true) is credited when
another line of the target runs the same check unmasked. Under.ONESHELLthis holds only
when the mask is a pure no-op (true,:,echoorprintfof literal words) and every
statement of the recipe is plain; aPATH=line only warns.- Scripts and actions are read up to 1 MiB (was 64 KiB), for
ci.tamperedand for the scripts a
policy command runs. A step's reading budget is 32 files and 2 MiB (was 512 KiB). Past a cap,
a change to what the file runs warns.
Fixed
- A quoted
;,},)or|in a CI command is an argument, not a terminator, so a group
around a check no longer turnstests;or}into a selection. - A Makefile
includeguarded by a wildcard test of its own file no longer warns.
Full changelog: v0.3.1...v0.4.0
greenproof 0.3.1
Install: uvx greenproof@0.3.1 --version or pipx install greenproof==0.3.1 (PyPI).
Fixed
- An interrupted check no longer waits forever for the process it killed. When SIGINT or
SIGTERM arrives while a policy command or the smoke start command runs, greenproof's handler
raises insidePopen.waitorPopen.poll, and that leaves the Popen's internal lock held
about once in a hundred signals: 95 of 8,576 timed waits on CPython 3.11, 62 of 6,847 on 3.12
and 67 of 6,781 on 3.14. After that no wait on the process returns, so the unbounded wait
after SIGKILL hung. It is now bounded at two seconds (also when thegit cat-filereader is
killed), and the process is reaped when greenproof exits. CI showed it as a 30-second timeout in
test_sigint_removes_the_worktree_and_kills_the_command.
Changed
- CI, the release workflow, the GitHub Action and the workflow that
greenproof init --ci github
writes use astral-sh/setup-uv 10.3.3.
Full changelog: v0.3.0...v0.3.1
greenproof 0.3.0
Install: uvx greenproof@0.3.0 --version or pipx install greenproof==0.3.0 (PyPI).
Measured against 0.2.0 on the same inputs (MEASUREMENTS.md): of 684 tamper probes, 638 block
and 46 warn (0.2.0: 187 and 42); of 450 honest probes, 2 block (0.2.0: 87). On real history,
75 of 698 test-touching commits block (0.2.0: 70), 21 of them false blocks (0.2.0: 20).
Added
scripts/release_notes.py X.Y.Z, which prints the GitHub Release notes for a version: the
install line, that version's CHANGELOG section and the compare link from the previous
release.tests/test_release_notes.pyruns it against the real CHANGELOG.- The release workflow checks that CHANGELOG.md has a section for the tag before it builds
anything for PyPI, and after PyPI accepts the upload it creates the GitHub Release with that
section as the notes and the built files attached. - Link references at the end of the CHANGELOG for each version and for
[Unreleased]. - A report note on the default branch with no upstream: only uncommitted changes are checked,
and--base REFincludes commits.bench/replay.pytakes--select runner(commits that
touch CI, runner configs,package.json, Makefiles or shell scripts) and--command CMD. runner.tamperedreads more of what chooses which tests run. tox and nox: thecommandsof
each tox environment and each nox session are read, and a-prefix on a check
(commands = - pytest),ignore_errorsorignore_outcomeon an environment, a nox
success_codeswidened ([0, 1, 5],range(10)), asession.runinside atrywhose
exceptswallows it, a check dropped (ruff check .becameecho skipped) and a nox
session.runpath narrowed (teststotests/test_shop.py) block.{envpython},
{toxinidir}and{[section]key}are normalised first, sopython -m pytestforpytest
passes, and a workflow step that runstoxornoxis judged the same way. A baretoxor
noxis judged by what its default environments or sessions run, so a shorterenvlistor a
narrower{posargs:...}default blocks. Also read as
selection: Go-tagsdropped or narrowed; jest and vitest path flags (--testPathPatterns,
--dir) and changed-file flags (--changedSince,--onlyChanged,--lastCommit,
--changed,--related); cargo target kinds (--lib,--bins,--bin,--test,--doc,
--example),--workspacereplaced by-p, and a dropped--featuresor--all-features.
Widening passes.- Monorepo package filters are selection, in
runner.tamperedandci.tampered: turbo
--filter/-F(including!docs), pnpm--filter/-F, nxrun-many--projects/-pand
--exclude, lerna--scope/--ignore, and yarnworkspaces foreach--include/--exclude.
A filter added where the base had none, or one that leaves out a package the base ran, blocks
(turbo run testtoturbo run test --filter=web); a dropped or widened filter passes, and a
rename or a glob (webtoapp-*) warns. Inrunner.tampered,nx run-manybecoming
nx affectedwarns. - A test command that names exact test files covering every file the base path selected
(pytest .topytest test_shop.pywhen that is the only test file) is a warn in
runner.tampered, in any directory, and says that test files added later will not run. Fewer
files, or a test file added in the same change, still blocks. runner.tamperedreads these as selection: pytestpython_files,python_classes,
python_functions,testpaths,norecursedirs,--doctest-modulesand--doctest-glob,-o
and--override-iniof any of them, and the keys of jest (roots,rootDir,
modulePathIgnorePatterns,testRegex), vitest (dir) and mocha (spec,ignore,
recursive) that choose or ignore test files. Each pytest run is judged from the config's
addopts, thenPYTEST_ADDOPTS, then the run's own flags (a command-line-obeats
addopts), following the run throughmake(-Cincluded),npm runand shell scripts. A
flag moved betweenaddoptsand the command line passes, and one dropped from a command line
blocks. With more than 8 different pytest runs the runs are not compared one by one: the
configuration alone is judged, and a change to the runs warns.- Makefile reading follows
includefiles (literal paths, simple variables,$(CURDIR)and
$(dir $(lastword $(MAKEFILE_LIST)))),definemacros used through$(call ...),
conditionals (ifeq,ifdefand the like, read as alternative worlds, so an honest edit in
one branch passes and a swallow in any branch blocks), double-colon, pattern and
multi-target rules, and aGNUmakefilethat make reads beforeMakefile. - Makefile recipes are judged in the directory they run in (
cd dir && ...,make -C dir),
target-specific variables are read in one pass, and a Makefile read only in part still judges
the goal's recipe.set -o pipefailkeeps a pipeline's status whenSHELLis bash, a line
that masks a check is credited when another line of the target runs the same check unmasked,
and a touched line with$(call ...)or$(eval ...)warns, once per target. ci.tamperedjudges abranchesorbranches-ignorefilter added underpush: it passes
whilepull_requeststill runs on every branch, and warns when it takes the default branch
(mainormaster) offpush, or whenpull_requestis itself filtered or gone from the
workflow (a droppedpull_requestalso blocks, as before). It also reads kept exit statuses:
rc=$?; ...; exit 0swallows the check,exit $rckeeps it.
Changed
- Base resolution: on the default branch the base is the merge base with the upstream, so
commits not yet pushed are checked with the uncommitted changes. With no upstream, or HEAD
equal to it (CI on a push), only uncommitted changes are compared. An upstream that shares
no history with HEAD (a shallow clone) is exit 4 with thefetch-depth: 0hint, not a
silent fall back toHEAD. - Python test analysis:
tests.weakened(block) now fires for a test removed by a laterdef,
delor rebinding of its name, a swallowing decorator added to a test,assert [x]or a
non-empty string or tuple,x == x, and an exact numeric check loosened to apytest.approx,
math.iscloseorassertAlmostEqualband of 1% of the expected value or more. A bare
pytest.approx(99), a tight tolerance and a retry or cleanup decorator that re-raises pass. - A comparison with a call (
f(x) == f(x),get_settings() is get_settings()) is a real
determinism or singleton check and passes, unless it replaces a comparison of that call in
the same test (assert refund(100) == 99to== refund(100)), which blocks.delof a base
class that tests subclass removes no tests. - Helper credit follows imports of test-path modules and of test-support modules (those that
importpytest,unittestorhypothesis, or sit undertesting,test_utilsor
pytest_plugin), up to 8 calls deep; application modules earn nothing. A helper or
conftest.pythat loses checks re-analyses the unchanged tests that use it (at most 300
files read and 200 compared, with no note at the cap); one that loses none does not. - Table folds: folding several tests into one table-driven test (a parametrized Python test,
it.each, a Go table, Rust#[case]) keeps itstests.replacedwarn, which 0.2.0 blocked,
only when the table runs, no row leaves early and the row values reach an assertion. It blocks
when an assertion sits inside atry/exceptortry/catchthat swallows the failure, when
it isassert a or bwithadepending on a row, or when a row carries askip,skipifor
xfailmark of a kind the folded tests did not already carry. A Pythoncase _or a Rust
catch-all arm that closes amatch,expect(() => f(row)).toThrow()and.rejects.*count as
assertions, and a keptxfailrow passes. A fold body past the reading budget keeps the warn
and says it is too large to check. - Python warnings:
tests.expected_changedalso fires when a@pytest.fixturereturns a
different literal, andtests.self_mockedwhen an added or changed autouse fixture patches
a callable the tests in its scope assert on. - Go, JavaScript and Rust test analysis:
tests.weakened(block) now fires for a top-level
barereturn,if (true) return;orx || trueguard before the checks, checks under
if falseor&& false,expect(X).toBe(X)self-equality of a call-free expression, and
fewer rows in anit.each,test.eachordescribe.eachtable. Call self-comparisons follow
the Python rule. Areturnthat is the body of a brace-lessif,else,fororwhile,
return expect(...), Go'sgot != gotand a table with a spread or a non-literal table pass.
Helpers in the same file (JS) or directory (Go) earn credit. - A Go
//go:buildor// +buildconstraint added to an existing_test.gofile that had none
istests.skipped(block); one that differs from the file's own warns. gofmt's migration to
//go:build, go fix's// +buildremoval and a constraint on a new test file give nothing. - Data files: a modified, or renamed with changed content, expected-output file (
.json,
.snap,.golden,.csvand similar) under a test path ortestdata,fixtures,golden
or__snapshots__istests.expected_changed(warn), once per file. Dependency, compose,
Dockerfile*,.pre-commit*,codecov.ymland.env*files and pure renames are skipped. ci.tampered(block) judges CI across all workflow files and looks through local composite
actions, local scripts,bash -cand launchers such asdocker compose runanduv run.
It blocks a swallowed check (|| true,|| echo,set +e,; exit 0under a shell with no
errexit),continue-on-error: trueorif: falseon a...
greenproof 0.2.0
OpenCode 2.x support, one plugin for Claude Code, Codex and Cursor, one decision per stop when the gate is installed twice, and greenproof check inside sandboxes that cannot write .git.
Install: uvx greenproof@0.2.0 --version or pipx install greenproof==0.2.0 (PyPI).
Added
- A plugin for Claude Code, Codex and Cursor (
plugins/greenproof) that installs the Stop
and SessionStart hooks without runninggreenproof init, with a marketplace file for each
agent (.claude-plugin/,.agents/plugins/,.cursor-plugin/). Each manifest names its
own hooks file, so no agent loads another's. The hooks runuvx greenproof@<version>,
pinned to the release; the plugin also carries a skill that tells the agent how to answer
a block. scripts/bump_version.py X.Y.Z, which sets the version in_version.py, the manifests and
every pinned command in the plugin, andtests/test_plugins.py, which fails when any of
them differs from__version__and checks each manifest against its vendor's format.scripts/make_icon.py, the standard-library script that draws the plugin icon.- An OpenCode 2.x plugin (
integrations/opencode, packageopencode-greenproof, also
packaged inside greenproof): on a top-level session going idle it runs
greenproof check --hook opencodeand continues the same run withctx.session.synthetic
on a block; a release is a console warning and every failure fails open. It starts a
session on the first prompt of a top-level session (theprompthook), skips subagent
sessions, runs one check per session at a time and gives way to a second copy loaded in the
same process. Plain ES module with onlynode:imports; 2.x only. greenproof init --agents opencodewrites.opencode/plugins/greenproof.jswith the hook
command set. The file is replaced only when its first line says greenproof wrote it; any
other file there is a usage error (exit 4) and nothing is written.--agents autoalso
installs it when.opencode/,opencode.jsonoropencode.jsoncexists.- A CI job that runs
node --teston the plugin (actions/setup-node pinned to a commit) and
checks thatnpm packlists onlyindex.js,README.md,LICENSEandpackage.json. scripts/e2e/opencode.py, an end-to-end run of the plugin in the real OpenCode CLI against
a fake OpenAI-compatible model server (--self-testchecks only the server). It is not
part of pytest.scripts/bump_version.pyalso sets the npm package's version and the command pinned in
its copy of the plugin.check --hook opencodeandsession-start --hook opencode, for the OpenCode plugin: the
payload carriessession_idandcwd, and the output is Codex's protocol (block, pass,
release) and Claude Code's session-start output.- Duplicate hooks for one stop. The gate can be installed twice (a plugin and the hooks
initwrites), and the agent then runs both in parallel. Everything after repository
discovery runs under an exclusive lock on<git-dir>/greenproof/hook.lock, the hook state
records the payload's fingerprint (a sha256 of the sorted, compact payload), the decision
and the block message, and a second hook for the same stop (same payload, same tree)
outputs that decision again (at most three replays) instead of finding the first one's
block and releasing the agent.
When the lock file cannot be opened, the hook runs without the lock. forkin the SessionStart matchers of the Claude Code and Codex CLI hooksinitwrites.
Both agents document it as a source; the session marker is kept, as forresume.
Fixed
greenproof checkin local mode no longer exits 4 when the git directory is read-only, as
in an agent sandbox that lets the agent write the working tree but not.git(Codex's
workspace-write):git add -Acould not store the snapshot's objects. When the snapshot
fails and a probe file cannot be created in the object directory, greenproof retries with
a temporary object directory (GIT_OBJECT_DIRECTORY, with the repository's objects as
GIT_ALTERNATE_OBJECT_DIRECTORIES) for every git command of the run, deletes it on exit
and writes nothing under the git directory, so no pass is cached. The revert check is
skipped with a note,--isolateexits 4, and the report carries a note. Hook and CI mode
still fail closed on a git failure.
Changed
- A pass is now recorded in the hook state instead of clearing it, so a duplicate hook for
the same stop can replay it. Nothing to verify still clears the state. A state file
written by 0.1.0 is read as a block with no fingerprint. suppress.addedapplies each generic pattern only where it has an effect.|| true,
; true,set +eand the git--no-verifypattern fire in shell-capable files (scripts,
makefiles, justfiles, CI and container files,package.json,pyproject.toml,
tox.ini,setup.cfg,.husky/and.githooks/), and--passWithNoTestsalso in
JavaScript and TypeScript. They no longer fire in.tomlcase files,.jsondata,
prose or source files of other languages.- The README says that
uvxhook commands needuvon PATH.
Full changelog: v0.1.0...v0.2.0
greenproof 0.1.0
First release.
Added
- The engine (
greenproof check): repository discovery, a snapshot of the candidate tree
(staged, unstaged and untracked files) taken with a temporary index so the user's index and
working tree are untouched, base resolution (--base, the pull request's merge base in
GitHub Actions, the session marker, the default branch), the policy and commands read from
the base revision, a command runner that kills the process group on timeout, a pass cache,
and text, JSON (greenproof/report@1, with a shipped JSON Schema) and Markdown reports,
plus GitHub annotations. - Exit codes: 0 pass, 1 blocking integrity finding, 2 command failed or timed out, 3 smoke
failed, 4 usage or configuration error, 5 internal error (fails closed). greenproof explain RULE_ID, and a[rules]table in the policy to set a rule toblock,
warnoroff.- Static rules for tests and checks that were weakened:
policy.changed,tests.deleted,
tests.removed,tests.replaced,tests.skipped,tests.focused,tests.weakened,
tests.expected_changed,suppress.added,runner.tampered,ci.tamperedand
static.parse_error. Python test files are analysed as syntax trees; JavaScript,
TypeScript, Go and Rust test files get line-level checks. tests.self_mocked(warn): an added or changed test that patches the callable its
assertions call (monkeypatch.setattr,mock.patch,patch.object,jest.mock,
vi.mock, a mockedspyOn) is reported as testing the mock.code.hardcoded(warn, Python only): non-test code that gains a literal table of eight or
more entries, or a branch on a literal the diff's tests just added.- The revert check (
revert.passes_without_change, warn): runs only the added or changed
tests against the base source with the candidate's test files overlaid, for pytest, jest,
vitest andgo test; other runners are skipped with a note. - The smoke check (
smoke.failed, block): starts the artifact in its own process group,
pollsready_url, runs the probes and always terminates the group. check --isolate: setup, commands and smoke run in a worktree of the candidate tree.- A check that is skipped says why in the report's notes.
- Agent hooks for Claude Code, Cursor and Codex CLI, and an experimental one for Gemini CLI:
check --hook AGENTspeaks each agent's stop-hook protocol, releases the agent instead of
trapping it (nothing changed, same tree after a block, or eight consecutive blocks), and
session-start --hook AGENTrecords the session's base and tells the agent what the gate
checks. - Finding fingerprints, and
greenproof accept FINGERPRINT... [--reason TEXT],--listand
--revoke. Local acceptances are advisory. In CI,--github-accepthonours
/greenproof acceptcomments from repository owners, members and collaborators only. greenproof init: detects Python, Node, Go and Rust projects and Makefile or justfile
targets, proposes[commands]from evidence, verifies them, and writes.greenproof.toml,
anAGENTS.mdsection, the agent hook files (--agents) and, with--ci github, a
workflow. It never prompts and never commits. It writesrevertinto[modes.ci]and
never writes a[smoke]table.- A composite GitHub Action (
action.yml) and a pre-commit hook (.pre-commit-hooks.yaml). - A release workflow: a
v*tag builds the package, checks that the tag matches its version
and publishes it to PyPI with trusted publishing, so no token is stored. - Dogfooding: this repository has its own
.greenproof.toml, AGENTS.md section and Claude
Code hooks, and agreenproofjob in CI that runsgreenproof check --mode cion pull
requests. - A README covering the problem, install, quick start, how a check works, the rules, agent
support and its caveats, CI, accepting findings, smoke setup and the limits. - A benchmark (
bench/run.py, 107 cases on Python, JavaScript and Go fixtures) and a
real-history replay (bench/replay.py). MEASUREMENTS.md reports the benchmark, a replay
of 698 commits from click, httpx, zustand and cobra with every block triaged, a Claude
Code end-to-end run, and the known false-block patterns. The raw results are in
bench/results/. tests.expected_changedalso reports a test whose expected value changed when no
non-test code changed (a test edited to match what the code returns).- Calibration from the replay triage. Tests pair across renames by leaf name, by a body hash
without the test's own name, and by a structural hash with identifiers renamed.
JavaScript countsexpectTypeOf,assertTypeand testing-library queries that throw
(getBy…, awaitedfindBy…) as checks, once per statement. Go counts calls to same-file
assertion helpers and no longer treats benchmarks as tests. A test inside a block
comment is not a test. A drop made only of loose checks, a removed test with no checks in
a file that gains tests, and suppressions in a newly adopted linter or type-checker table
are warnings, not blocks.
Changed
- The test suite runs in parallel with
pytest-xdist(pytest -n auto) in CI and in the
documented gate.
Install: uvx greenproof --version or pipx install greenproof. PyPI: https://pypi.org/project/greenproof/0.1.0/