Veritix is a one-person project with a commercial future, which shapes two things: contributions need a license grant before they can be merged, and a few design constraints are not open to being traded away for convenience. Everything else is ordinary.
Veritix is dual licensed — AGPL-3.0-or-later, or commercial terms — as
described in LICENSING.md. Contributions are accepted under
the Contributor License Agreement in CLA.md. You keep your
copyright; you grant the project the right to ship your code under both
licenses.
Signing is a Signed-off-by trailer on every commit:
git commit -s -m "Explain what the change makes possible"Adding that trailer means you have read CLA.md and agree to it for the
commit it is on. There is nothing else to sign. If you are contributing on
behalf of an employer, name the employer once in the pull request.
If you would rather not sign, a bug report with a reproduction, or a failing test that demonstrates the problem, is genuinely useful and asks nothing of you.
Read CLAUDE.md first. It is the orientation document for
picking this codebase up cold — what the packages are, why they are split that
way, and a list of gotchas that each cost somebody a debugging cycle. It is
not AI-specific; it is just where the working notes live.
make build test lint # what has to pass
make web # the web interface, into web/dist
make release # web, then build: the binary that ships an interface
make e2e # browser tests (see e2e/README.md)
make audit # dependency and vulnerability checks
go test -race ./... # before committing: profile, ingest and api all fan outgolangci-lint is not installed by the Makefile; without it make lint
falls back to go vet alone and will miss what CI catches. Install it with
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest.
Repo-wide lint is clean and should stay that way — fix the code rather than
widening .golangci.yml.
Commit messages say what the change makes possible, in the imperative, on one
line: "Serve audits over HTTP, with progress and an audit trail". The body, if
there is one, explains why. git log is the model.
Pull requests go to main. The maintainer commits to main directly — that
is not a standard anyone else has to meet, it is just what a project with one
reviewer looks like.
These are load-bearing. A change that weakens one is not a trade-off to be
discussed in review; it is a change to what the product claims to be. The full
reasoning is in CLAUDE.md, and each is pinned by a test.
-
Do not add a second way to get at raw cell values. Reports describe columns by derived shapes, not contents.
GET /runs/{id}/findings/{fid}/rowsis the single deliberate exception, asked for one finding at a time.TestDefaultReportContainsNoRawValuesandTestReportOmitsRawValuesByDefaultpin it. -
Do not weaken
Set.Verify. Every finding carries a re-runnableCountQuery, and a finding that no longer reproduces is dropped. For the agent this is the whole mechanism: the model chooses what to look at, the engine decides what is true. -
Do not route around
internal/agent/redact. It is the only path from the process to a model, and it is enforced by types rather than by care. A new tool that returns raw values should fail to compile into a leak. -
Do not add a runtime dependency to the web interface casually. It has three, it is served under a strict CSP, and the page can display customer data.
docs/frontend-stack.mdis the argument and the policy, including the release-age cooldown and the license constraint — a copyleft dependency cannot be adopted here, because the commercial license could not deliver it.
testdata/dirty-retail/ carries deliberately broken files with a defect
manifest in internal/checks/checks_test.go: 21 planted defects, each named
with the check that must catch it, plus a companion list of places the data is
clean and must stay quiet. A new check adds to both lists. A check that
fires on everything is useless, and only the second list catches that.
No test calls a real model. The agent's tests drive the real loop against a scripted provider; the API's tests point the server at a local HTTP endpoint speaking chat-completions. They are about what Veritix does with what a model said.
Do not open a public issue. Write to russell.wallace@gmail.com with enough detail to reproduce it. Anything that gets customer data out of the process — past the report redaction, past the egress guard, or past the CSP — is the category this project cares most about.