How verdicts are made
The five states a verdict passes through, the invariants publishing enforces, the nightly freshness pass, and the mirror to the public repo.
A verdict is not a summary of what people say. It is one reviewer's answer to one question, at a stated version, with the sources they read and the date the claim has to be checked again. The process below is what separates the two, and most of it is enforced by the code rather than by discipline.
Five states
| Status | Served | Meaning |
|---|---|---|
draft | no | Being written. |
review | no | Waiting for a reviewer. Accepted trap submissions land here too. |
published | yes | A named reviewer verified it at a version, on a date. |
recheck | yes | Still served, with the flag. A version moved or the expiry passed. |
retired | no | The evidence no longer holds. |
Only published and recheck reach the tools and the website. Retiring is deliberate: a verdict whose evidence stops holding is withdrawn rather than quietly edited, so the corpus never rewrites its own history.
What publishing refuses
Publishing runs in one transaction that locks the row and checks five things. Any one missing and the publish fails, naming exactly what is absent.
| Invariant | Why |
|---|---|
verified_by is set | Every served answer has a person behind it. |
verified_at is set | Verification is a date, not a state. |
version_tested is set | An answer with no version cannot go stale, which means it cannot be checked. |
| At least one source | A claim with no citation is an opinion. |
Exactly one node with role pick | Two picks is a comparison that has not been decided. |
The reviewer's identity and today's date are stamped at publish time, not by whoever wrote the draft, and a stale expiry is cleared so the publish grants a full window. If any invariant then refuses, the stamp is rolled back and the row is left as it was.
expires_at is set to verified_at plus 120 days, unless an earlier date is already on the row, in which case the earlier one is kept. Nothing can extend a verdict past 120 days without a person publishing it again. That number is the whole design: a claim about a library that nobody has looked at in four months is a claim you should not act on without checking.
The served block prints by wellworn reviewer rather than a name. The reviewer's identity is recorded on the row and in the audit log; it is not exposed in the tool output today.
The nightly pass
At 02:00 UTC the jobs service runs freshness, then the mirror.
Freshness reads every staff-written node that names a package registry, four at a time with a six-second timeout each, identifying itself as wellworn-signals/1.0. Catalog rows imported from elsewhere are skipped: the pass only touches nodes a verdict depends on.
| Registry | Read from | Version taken |
|---|---|---|
| npm | registry.npmjs.org | dist-tags.latest |
| PyPI | pypi.org/pypi/<name>/json | info.version |
| Packagist | repo.packagist.org/p2/<name>.json | newest non-dev, non-prerelease |
| crates.io | crates.io/api/v1/crates/<name> | max_stable_version |
| Go | not read | Go modules have no single index worth trusting, so they are skipped |
Verified 2026-09-08 against registry.npmjs.org
For a node with a GitHub repository, the pass also reads whether the repository is archived and what its latest release is tagged. Unauthenticated calls work but burn GitHub's hourly allowance quickly on a shared address, so the job sends a token when it has one.
What flips a verdict to RECHECK
After the registries are read, every published verdict's pick is compared against what came back. Two conditions flip it, and either is enough:
- The pick's latest release has a higher major version than
version_tested. Both are coerced with semver first, sov1.7.3and1.7.3compare the same way, and a minor or patch bump does not trip it. expires_athas passed.
The flip moves the verdict to recheck and moves every published trap on that pick to recheck with it, so the block and its warnings age together. Running the pass twice changes nothing the second time: the update only matches rows still in published.
Nothing clears the flag automatically. A reviewer re-verifies, which republishes the verdict with a new date and a fresh 120-day window and carries the pick's traps into the same window.
The mirror
Every served verdict is mirrored to the public repository as one YAML file at verdicts/<kind>/<slug>.yaml, in the same shape as the seed files plus the provenance fields: status, verified_at, expires_at, and the revision number.
Only verdicts whose revision has moved past what the mirror holds are considered. For each one the file is rendered, its git blob sha computed locally, and compared with the sha already recorded. An unchanged render costs no request at all; a changed one is a single write to the GitHub contents API with the message publish <slug> rev <n>.
Staging deliberately has no GitHub token, so a staging deploy can never write to the public corpus. Without a token the mirror step logs that it was skipped and the freshness pass still runs.
Reading the result
Every published verdict is browsable with its sources, its reviewer date, and its recheck date. The same rows are in WellWorn-dev/wellworn as YAML, under CC BY-SA 4.0. If a verdict looks wrong, contributing is the path to say so.