bitexoft-verify

The platform's only definition of "correct". It runs in two places and decides the same thing in both:

The difference shows up as provenance.surface in the report. The platform marks a delivery as verified only on a green CI report.

Install

Python 3.10 or newer — the version Ubuntu 22.04 LTS ships, so a stock Linux works without upgrading anything.

pip install bitexoft-verify            # core; one small dependency below 3.11
pip install 'bitexoft-verify[api]'     # adds what later deliveries need to verify APIs

If pip answers requires a different Python, check your version with python3 -V. The project itself targets a newer Python than the tool does: each delivery's contract states what it needs.

Use

bitexoft-verify check A1          # verify A1
bitexoft-verify check A3          # verify A3 and, on the way, A1 and A2
bitexoft-verify check A3 --only   # just A3
bitexoft-verify deliveries        # what this version can verify

Exit codes: 0 all green, 1 something fails, 2 could not even start.

bitexoft.toml

Organise your project however you like. You declare it here and verification reads it from here; what is not negotiable is the shape of the boundaries, not their names.

[project]
id = "chaos-sports-lab"
package = "chaoslab"

[layers]
domain = "chaoslab.domain"

[cli]
module = "chaoslab"        # run as `python -m chaoslab`
# main = "main.py"         # or a script, if that is your entry point

The three gates

• Acceptance — that it works: the contract's symbols, impossible objects refused, value semantics, the geometry, the entry point and its exit codes.
• Design — that it is built well: the domain's boundary read from the syntax tree, your tests passing, at least one test that builds an impossible object.
• Evidence — that you understand it. The CLI does not judge this gate: it always reports skip with a message. You close it on the platform by writing the why and comparing it against the rubric.

A check never fails for something you cannot fix: if an optional dependency or a git tag is missing, it skips with a message saying what to do.

Cumulative verification

Verifying A3 also runs A1 and A2, with inherited checks tagged [A1]. That is what makes the method agile: every delivery leaves the whole project standing, and a regression in old work shows up while verifying the new.

The sample files

Deliveries are verified against files the CLI ships with, not against one you wrote. For A1 that is 30 instants crossing all three block states, plus a copy with one coordinate off the pitch to check that bad data fails cleanly instead of printing a traceback at the user. They are synthetic: no third-party data is distributed here.

Development

pip install -e '.[dev,api]'
pytest                               # builds a fake learner repository and verifies it
ruff check .
python tools/make_fixtures.py        # regenerate the sample files

Before changing what a check says when it fails, or the layout of the output, read docs/foundations/03-feedback-self-explanation-calibration.md (the verifier's messages are the feedback a learner reads) and ADR 0002. The check ids and the report schema are a contract with the platform: do not rename them.

Releasing

The version is written once, in __version__ (src/bitexoft_verify/__init__.py). The pin in .github/workflows/verify.yml (cli-version) must match its major.minor; a test checks it.

First release, by hand on pypi.org:

1. Account → Publishing → Add a pending publisher: project bitexoft-verify, owner bitexoft, repository sports-lab-v1, workflow release-verify.yml, environment pypi.
2. In the repository settings, create the environment pypi.

Each release:

git tag verify-v0.2.0 && git push origin verify-v0.2.0

The workflow runs pytest on 3.10 and 3.12, refuses a tag that differs from __version__, builds with python -m build and publishes with trusted publishing (no tokens). Check it in a clean environment: pipx run --spec bitexoft-verify bitexoft-verify deliveries.