This is the development record, published as it was written. It is amended by revision, including where the work went wrong. Nothing here has been rewritten for the web.

Adding a check

A check is a small function over a snapshot of a site. If you can write a test for it, you can contribute it.

The rules

1. It must be deterministic. Same snapshot in, same result out. No clock, no randomness,

no network, no model.

1. It must state a fact, not a prediction. Never claim or imply that an agent will find,

trust or recommend the business. tests/test_checks.py::ClaimBoundaryTests enforces a short list of banned phrasings; the spirit matters more than the list.

1. It must say what evidence would change its mind. Return the evidence strings that

produced the verdict, so a supplier can check your work.

1. It must declare its basis. evidence if the requirement comes from published practice

or a measured result; judgment if it is our opinion. Do not upgrade an opinion.

1. **A failure to determine is unknown, not a pass.** If you cannot evaluate the check,

return UNKNOWN and say why.

The shape

Add to eligibility/checks.py:

@check(
    id="reach.example",                 # category.slug, stable once published
    category="reach",                   # reach | identity | offering | navigation
    title="Short title shown in the report",
    question="One sentence, phrased as a question about the site.",
    why="Why an agent cares. One or two sentences.",
    basis="evidence",                   # evidence | judgment
    weight="core",                      # core | recommended
    remediation="What the supplier should do about it.",
)
def reach_example(snapshot: Snapshot, facts) -> Outcome:
    blocked = _blocked(snapshot)
    if blocked:
        return blocked
    if something_is_true:
        return (PASS, "A sentence a supplier can read.", ["the evidence that shows it"])
    return (FAIL, "What is wrong, in plain words.", ["the evidence that shows it"])

facts is a PageFacts parsed once per audit. Use it rather than re-parsing snapshot.page.text.

What you may rely on

• snapshot.page, snapshot.robots, snapshot.sitemap, snapshot.llms — one bounded fetch

each, already performed. Checks never fetch.

• facts.types(), facts.nodes_of_type(...), facts.jsonld_objects() for structured data.
• parse_robots(snapshot.robots.text) for the crawler policy.
• looks_like_xml, count_xml_locations for XML surfaces.

Anything else you need, add to PageFacts — and keep the parser small.

Then

1. Add a test in tests/test_checks.py. Every check needs at least one passing and one

failing case. If it can be unknown, test that too.

1. Run make rubric. This regenerates docs/RUBRIC.md; CI fails if you forget.
2. Run make ci. It must exit 0.
3. Open a pull request that says what the check establishes and what it does not.

What will be rejected

• A check that needs a third-party package. The runtime is standard library only.
• A check that requires crawling beyond the one page and the three well-known files.
• A check whose wording promises a ranking, a recommendation or a traffic outcome.
• A check that fails a site for a convention that is not yet established practice.

Mark it judgment and make it recommended instead.