truedone

Checks whether a pull request's tests prove its change: red without it, green with it.

What each truedone label means

truedone gives every pull request one verdict and sets at most one label. The labels come in the order truedone ranks the verdicts, highest first. Not applicable sets no label.

truedone:tampered

Tampered

Given when: A test that existed at base is disabled, focused or weakened, and nothing equivalent is added; or this PR removes, edits or re-pins the truedone step, other than to a published truedone release

What to do next: Restore an equivalent test, or pin the step to a published release.

Example: Truedone/truedone-sandbox#31, a pull request that weakens an assertion.

truedone:review

Test changes: review

Given when: Tests moved, removed or rewritten in a way that may be legitimate (a snapshot update, a parametrised case dropped, a deleted test whose source was deleted too); a raised timeout; a change to the test runner config, a setup file, the test script or the workflow that holds the truedone step; the truedone step moved to a newer published release

What to do next: Confirm the test change is intended.

truedone:could-not-run

Could not run

Given when: No test reached a result: the runner, a service or a setup step was missing, the results were flaky, or a run errored or timed out. The reason is named

What to do next: Fix the named reason and run again.

truedone:yes

  1. Tampered
  2. Test changes: review
  3. Tests changed: not run
  4. Proven

Green comes from running the tests: add the truedone step (not released yet).

Proven

Given when: A test in the PR fails on base by assertion (twice), passes on head (three times out of three), and runs lines the PR changed

What to do next: Review the rest of the change as usual.

Proven (new behaviour)

Given when: A test fails on base only because a function or module the PR adds does not exist yet. On head it passes three times out of three, makes at least one assertion on that new code's result, and runs lines the PR changed. Without that assertion it is Proven (weak)

What to do next: Review the rest of the change as usual.

truedone:weak

Proven (weak)

Given when: Red-green holds, but the test runs none of the changed non-test lines or asserts nothing about them

What to do next: Make the test run the changed lines and assert on them.

truedone:no-evidence

No red-green evidence

Given when: Source changed, and no test in the PR fails without the change

What to do next: Add a test that fails before the change and passes after it.

truedone:pending

Waiting for approval

Given when: Tests changed and the repository has the truedone step, but GitHub is holding the run for a first-time contributor. The static findings are shown meanwhile

What to do next: Approve the run on GitHub.

truedone:unrun

Tests changed: not run

Given when: Tests were added or changed with nothing weakened, and no red-green has run: the repository has no truedone step, or the verdict comes from truedone.pages.dev or the static CLI

What to do next: Run the changed tests: the next rung.

Next rung: run the PR's own tests on your machine

The verdict pages read the diff only. To run a pull request's own tests against base and head, run:

npx truedone <PR link> --run

The action is not released yet: follow the first release.

Red-green on someone else's PR executes that PR's code on your machine; --docker runs it in a container.

For your own agent, the truedone Claude Code plugin runs the same checks before it reports a task done.