v0.5.3 — The judge was rating projects it had not read

This release changes what SpecJudge recommends. It is a bug fix, and the version
number says so — but the effect is not cosmetic, and it is worth two minutes before you
upgrade.

The judge was rating projects it had not read

The compact prompt sends a digest instead of your artifacts. That digest was built from
text that had already been truncated, so it summarised the first 1,500 characters of
each file and said nothing false about them. Which is why nothing caught it.

On a real feature — the first live run of the spec-kit extension — the judge received
this, in full:

spec: 1340 chars
  sections (4): Feature Specification… | Context | User Scenarios…
tasks: 1429 chars
  sections (3): Tasks: Wiki multiproyecto | Format: `[ID] [P?]…`

No requirements. No tasks. FR-001 sat at line 82 of the spec and T001 at line 41, both
past the cut. Of 28 citable fragments, 22 were section headings.

So a rewrite of access-control resolution — 20 requirements, 29 tasks, the kind where a
silent regression leaks one client's content to another — came back reasoning: medium, size: low, recommended for an 8B model, citing the title of the tasks file as evidence.

What changed

A digest is bounded by its own structure, not by the length of the document it describes.
Truncating the summariser's input was the wrong way round.

• Built over the whole source, with the budget applied to the finished digest.
• Every named unit carries its own text, so it stays citable and verifiable — a catalogue
  of bare ids would turn a citation into a label picked from an inventory.
• Samples span the file. A task list opens with setup and closes with the hard part; a
  sample taken from the head describes the easy end and then decides the difficulty from
  it.
• Counts come from the whole file even when the sample does not. The tool was already
  computing "29 tasks" and throwing it away while the judge answered size: low.

Measured on the 18-project regression corpus:

Judge	Before	After
devstral-small-2 (24B)	30/30 in band	32/32, two more dimensions graded
qwen3:8b	25/28 (89%)	26/30 (87%)
llama3.1:8b q4	22/27 (81%)	24/32 (75%)

Read the denominators with the percentages: more of each project now reaches the judge, so
there is more to be right or wrong about. llama3.1 answers five more dimensions and gets
more of them wrong.

Also fixed

• Unfilled template placeholders ([PRINCIPLE_1_NAME]) are no longer offered as
  evidence. An untouched spec-kit constitution was contributing eight of them.

• The constraint table resolved citations against the wrong fragment set for judges
  above the compact-prompt threshold, so it came out with no text and every row marked
  customary — silently, and only for people running a large judge.

• The spec-kit extension's install command. --from supplies the source, it does not
  replace the name. Extension 0.1.2:

  specify extension add specjudge --from https://github.com/JoaquinRuiz/SpecJudge/releases/latest/download/spec-kit-specjudge.zip

A recommendation that changed

The quick start now suggests qwen3:8b instead of llama3.1:8b, and
docs/judges.md
states the trade instead of a headline: it is wrong half as often and half as far off, and
where it cannot cope it refuses rather than answering — costing about one project in
eighteen its recommendation. If you would rather always get an answer and judge it
yourself, the other one is the other side of that trade.

Which 8B matters more than the fact that it is an 8B. Two models of identical size and
price sit twelve points apart in that table.

Upgrading

pip install --upgrade specjudge

No API, schema or exit code changed. What changed is the input the judge receives, and
therefore its answers. If you keep recommendations under review, expect movement on
projects with long artifacts.

Full detail in the changelog.