claimset

Quickstart

Three steps. No account, no service, no network effect to wait for.

1. Write claims.json

   Pick the facts that would embarrass you if they went stale — deadlines, thresholds, prices, eligibility rules — and for each one copy a verbatim span from the primary source. Not a paraphrase: a paraphrase cannot be checked by string comparison, and a checker that scores paraphrases is making a judgement call you would then have to trust.

   {
     "claimset": "1",
     "publisher": "Example Shop",
     "contact": "https://example.com/corrections",
     "claims": [
       {
         "claim_id": "refund-window-30-days",
         "assertion": "You must request a refund within 30 days of delivery.",
         "source_url": "https://example.com/refunds",
         "checked_on": "2026-08-15",
         "expires_on": "2027-02-15"
       }
     ]
   }

   A good assertion is one clause with a number in it. Too vague and the verifier refuses it as WEAK before fetching anything; too long and the next copy-edit on the source breaks it for no reason.

   To find spans that will actually match, print the source the way the verifier sees it:

   claimset extract https://example.com/refunds --grep "within 30 days"

   Then choose expires_on honestly. It is the question "how long am I willing to vouch for this?", answered at the moment you know the answer. A regulation page might get 180 days; a price might get 30.

2. Run the verifier

   Availability. There is no published package yet — pip install and npm install are coming, not available, and any command telling you otherwise today is wrong. The reference verifier is one Python file with no dependencies (Python 3.9+, standard library only), and the public repository is publishing soon. Until then, run it from source:

   python claimset.py verify claims.json

   What comes back:

   $ claimset verify demo.claims.json --today 2026-08-15
   
   claimset 0.1.0: demo.claims.json (4 claims, as of 2026-08-15)
   
     PASS         support-reply-two-days  source still says it
     DRIFT        refund-window-60-days   the source matches the first 62% of this assertion, then diverges
                                          you claim : "you must request a refund within 60 days of delivery."
                                          page says : "you must request a refund within 30 days of delivery. support replies within 2 business days."
     EXPIRED      old-refund-window       expired on 2026-01-10; re-verify and re-date it
     WEAK         shipping-is-free        2 significant word(s), 0 number(s); need 4+ significant words, or a number plus 2+ significant words
   
     PASS 1  DRIFT 1  EXPIRED 1  WEAK 1
   
   FAIL: 3 claim(s) need attention. Fix the page, fix the claim, or re-verify and re-date it.
   
   $ echo $?
   1

   Exit 0 means every live claim still matches. Exit 1 means at least one needs attention. Exit 2 means the run could not happen at all — a bad file or an unknown format version — which is an absent check, not a failed one, and is deliberately a different code.

   Other commands: claimset lint claims.json checks structure and falsifiability with no network requests at all, which is what you want on a pull request; claimset extract <url> prints a source's normalised text.

3. Wire it into CI

   The scheduled run is the one that matters. A repository with no commits this month is exactly the one whose facts have quietly rotted.

   # .github/workflows/claims.yml
   name: claims
   on:
     pull_request:
     schedule:
       - cron: "0 7 * * 1"     # Monday morning: sources change on their own calendar
   
   jobs:
     verify:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-python@v5
           with:
             python-version: "3.12"
         - run: python claimset.py verify claims.json --user-agent "claimset-verify/0.1 (+https://example.com/bot)"

   This runs the verifier directly, so it depends on nothing but the file in your repository. A packaged GitHub Action ships with the public repository.

   Two settings worth knowing before the first red build:

   • UNREACHABLE fails by default, on purpose — "I could not check" is not "nothing is wrong". --allow-unreachable exists for genuinely flaky sources; leave it off on pull requests.
   • Append your contact URL to the user agent. The verifier re-fetches other people's pages on a schedule, on your behalf. It honours robots.txt and rate-limits itself to one request per host per second; do not remove the brakes.

Then publish it

Nothing is required beyond committing the file, but two habits make it worth more: serve it at a stable path — /claims.json is the suggested convention — and link it from the pages whose facts it backs, with words to the effect of check these yourself. This site does both.