This is the main source repository for Swarm Verify, maintained under the swarm-orchestrator repository name. It also contains the optional beta coding agent. The separate moonrunnerkc/swarm-verify repository distributes the GitHub Action.

The recording is a real run of the published package over a committed evidence bundle: it verifies, one byte of one record is changed, and the altered bundle is refused with the broken link named. That is integrity. Who signed a bundle, and whether the tests it records measured the right thing, are separate questions the verifier answers separately (transcript, script).

npx swarm-verify

Run it in a git repository whose dependencies are installed (npm ci, pnpm install --frozen-lockfile or uv sync; it names the missing step and exits 4 when they are not). It reads the checks the project declares, runs them unattended the way a CI job would, and reports apart: whether the command ran, what each check found, how the commands were contained, and what it did not judge. By default it does not challenge the checks and does not judge whether the work is correct: a pass is a regression-only pass, and the result line says so. A failed check exits 1 and names the check; a check whose result cannot be trusted, such as a pass reported by a test configuration the change itself edited, exits 4 and says why.

It creates no swarm.toml and keeps its evidence outside the repository, under ~/.swarm/sessions by default. While it runs it briefly adds, then removes, its own swarm-falsification-bond.* fixtures to show each passing check can fail, and the project's own commands may write build output, caches or other files as they always do. No model, key or configuration is needed.

Needs Node 22 or newer, git, and uv for a Python project. Linux and macOS run every command; Windows runs bundle and verdict verification only. Locally, commands run on the host with a built environment and no credentials, which is a policy and not a sandbox; the Action runs them in a network-disabled container.

In CI

One job, one Action, the permissions a signed comment needs (the complete workflow):

name: swarm-verify
on:
  pull_request:
permissions:
  contents: read
  pull-requests: write
  id-token: write
  attestations: write
  artifact-metadata: write
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: moonrunnerkc/swarm-verify@v1
        with:
          install: true # install from the lockfile, scripts off, then run skipped scripts offline; omit for a project with no dependencies

The Action fetches the pull request's head and base by commit id into a checkout it owns, runs the project's checks in a network-disabled container, signs the verdict as a GitHub artifact attestation, and posts one comment bound to the head that says what was measured and what was not. A route for forks and Dependabot is documented; what has been exercised on a real fork is recorded in the completion index. Inputs, outputs and how to verify a signed verdict from outside the run are in the broad-use guide.

What it says, and what it does not

regression: pass means no check failed because of the change. It does not mean every check passed: a failure the base commit already had, the same way and in the same tests, is shown as inherited and does not count against the change, and the report names those failing tests. It does not mean the work was done either.

A requirement contract (swarm-verify ci --goal-contract) defines what the work must do, and the contract's checks are the evidence for each requirement. Neither the contract nor a signature proves the code is semantically correct. --challenges report asks whether each requirement's check could have caught wrong work (does it reject the tree before the change, mechanical mutations of the change, a fixture sealed as a violation) and reports gaps; --challenges required refuses on a gap; off asks nothing.

Every run exports a bundle carrying its own dependency-free verifier. Integrity, signer identity, execution trust, regression, task acceptance and challenge coverage are reported as separate answers, and unmeasured is one of them.

Where to go next

The full documentation index is docs/README.md.

Contributing

The bar is the one the tool applies to itself: npm run gates green with the output shown, new behaviour covered by a test that failed first, and no claim in a document that its linked artifact does not establish.

1. Fork the project
2. Create a branch (git checkout -b feature/amazing-feature)
3. Run npm run gates and paste the real output in the pull request
4. Commit (git commit -m 'Add an amazing feature')
5. Push (git push origin feature/amazing-feature)
6. Open a pull request

(back to top)