v0.3.0 — Something you can build on

Until now SpecJudge was something you ran. This release makes it something you can build
on — from any language, not just Python.

Nothing here is breaking. Upgrading from 0.2.0 needs no action.

A contract you can pin, in any language

--json has always worked, but it carried no version and was described in prose in a spec
document. That is fine to read and useless to depend on: you could not pin anything, and
you would find out it moved when your parser broke.

Now every payload carries a schema_version, and there is a real JSON Schema you can fetch
without cloning the repo or reading a line of Python:

specjudge --print-schema > specjudge.schema.json

Generate types from it, validate against it, pin to it. The rules are written down: adding
a field is a MINOR bump, removing one or changing what a value means is MAJOR. The version
is deliberately independent of the package version — otherwise the contract would appear to
change every time somebody updated a price in the catalog.

Two things the schema pins tightly and two it deliberately leaves loose. rating and
evidence.status are closed vocabularies — the first is fixed by the project constitution,
so widening it needs an amendment, not just a release. But demand levels and dimension names
come from rating-rules.yaml, which you are encouraged to edit, so they are typed as plain
strings. Enumerating them would have made the published schema wrong for anyone who
customised their rules.

And a Python entry point that is actually a promise

from specjudge import api

comparison = api.analyze("path/to/project", judge_model="llama3.1:8b")
print(comparison.best_choice)

Sixteen names, listed in docs/api.md,
and everything else under specjudge.* is explicitly internal and free to change in a patch
release. That second half matters as much as the first: a surface with no stated edges is not
a stable API, it is an accident waiting to be relied on.

The errors are exported too, each carrying the exit code the CLI uses, so you can tell "this
project cannot be judged" from "your environment is the problem" without matching on strings.

Also in this release

The README now states the Ollama 0.5.0+ requirement that 0.2.0 introduced. It had only
ever appeared in the changelog and in the error message you hit — which is exactly the wrong
order. It also documents the cited evidence the judge has to provide, which 0.2.0 shipped
without ever explaining on the front page.

And a small embarrassment fixed: the HTML report was advertising Del vibe coding al
Spec-Driven Development as forthcoming, without a link, when it had been on sale since July
— and omitting Explora la Inteligencia Artificial entirely. It shipped that way twice. The
cause was the same list living in two files with nothing tying them together, so there is now
a test that compares them and rejects a book that is both linked and marked as forthcoming.

Upgrading

Nothing to do. schema_version is a new field, and adding one is additive by the contract's
own rules: a consumer written against the 0.2.0 payload keeps working and simply gains a
version to pin against.

One thing worth knowing if you were already importing from the package: the public surface is
specjudge.api and nothing else. If you were reaching into specjudge.cli for the
serialiser, it now lives in specjudge.serialize and is re-exported as api.to_dict.

Full changelog: https://github.com/JoaquinRuiz/SpecJudge/blob/main/CHANGELOG.md#030---2026-08-06