About the Ground-Truth SEO Scanner

Scored rules

70

Categories

16

Registered sources

98

Ruleset

2.0.0 · cutoff 2026-09-28

What it is

The Ground-Truth SEO Scanner audits a website against what search engines, web standards bodies and AI crawler operators have actually documented. Every point in its score traces to a rule, every rule to a primary source, and every source to a dated passage quoted word for word. Scan the same snapshot twice and the report comes back identical, byte for byte.

That combination is the product. Most SEO audits grade sites against folklore: sixty-character titles, one H1 per page, a minimum word count, a mandatory meta description. Google contradicts several of those beliefs in its own documentation. This scanner reports only what it can verify, weights each finding by the strength of the evidence behind it, and says plainly when a question cannot be answered from outside the site.

Book With Haven builds and maintains the scanner and publishes it at SEOscanner.app, the name its logo carries. The knowledge base derives from The Ground-Truth Guide to Modern SEO (Dustin Hofer, Book With Haven) and its developer specification. Rule IDs match the book's requirement IDs, so the book, the scanner and any content system built to the specification share one vocabulary.

Who it serves

Platforms that generate many sites from shared templates come first. Book With Haven is the motivating case: a wrong canonical rule in one template ships to every customer site, so the audit has to be precise enough to trust and repeatable enough to run in continuous integration on every deploy.

Site owners and developers are the second audience. They need to know what is actually broken, in what order to fix it, and how to confirm the fix worked. Consultants and agencies are the third; every recommendation they hand a client should be defensible with a citation rather than a reputation, and the output is built to be forwarded as it stands.

Six principles

1. Scored against the best you could do. The score measures distance from the best setup the engines and standards document, so a practice counts whether or not the site has started on it. A missing sitemap, description or site name is an opportunity that lowers the score, with the passage that recommends it. Every check still rests on a primary source registered in the source registry, because the source is what makes the advice worth acting on; stricter house conventions appear labeled as conventions, with zero weight unless a team opts in.
2. Strength is preserved. “Must”, “recommend”, “supports” and “ignores” are different claims. The scanner weights them differently and never promotes a recommendation into a requirement.
3. Deterministic by construction. The network is touched once, during acquisition. Evaluation is a pure function of the stored snapshot, the ruleset version and the configuration.
4. Every number explains itself. Each finding carries the observed evidence, the expected state, a reason assembled from those values, a recommendation and at least one verbatim citation. The headline score is printed with its arithmetic.
5. Honest about limits. A check that needs data the scanner cannot see (server logs, Search Console, editorial intent) reports as manual or not evaluated, with the reason. It never guesses.
6. No ranking claims. The score measures how much of the documented best setup is in place. It does not predict rankings, traffic or citations in AI answers.

That sentence appears on the first screen of every report. A site can satisfy every documented requirement and still not be indexed, and the scanner would rather say so than imply otherwise.

What it deliberately leaves out

Content quality, helpfulness and expertise. Rankings, traffic and click-through. Backlinks and third-party authority metrics. Keyword density, word count, and title or description length. Lab performance scores.

Some of these lack published, testable criteria: Google publishes questions for creators, not a rubric. Others are explicitly dismissed by the engines. A few need data the scanner never sees. In each case the report says which, pointing to the myth guard, rather than substituting a proxy. Content still matters to site owners, so an optional advisory review offers editorial suggestions on titles, descriptions and answers to visitors' questions. It sits outside the score and is labeled as model output wherever it appears.

The methodology in depth

Each page below covers one part of the method, from how the score is calculated to the registry of every source the scanner may quote.

• How the score is calculatedWhy the score measures distance from the best documented setup, evidence classes with fixed weights, opportunities, indexing gates, exact rational arithmetic and a worked example.Read
• Evidence classes and citationsHow a documented must, a recommendation and a web standard become different classes, and why every finding carries a verbatim quote.Read
• Deterministic by constructionWhy the same snapshot always produces the same report: one acquisition, a frozen snapshot, and evaluation as a pure function.Read
• The rule catalogEvery rule the scanner evaluates, grouped by category, with its class, weight, gate and the primary source it rests on.Read
• What the scanner never scoresThe myth guard: claims that circulate widely and are contradicted, dismissed or unsupported by the primary record.Read
• The manual review checklistDocumented requirements that cannot be decided from outside a site, with the reason the scanner cannot judge them.Read
• AI crawlers and generative searchHow the scanner reports access for search and AI crawlers without scoring it, using each operator's own documentation.Read
• The advisory AI content reviewAn optional, clearly labeled model review of titles, descriptions and answers that never touches the score, and the guidelines that bound it.Read
• Source registryEvery primary source the scanner may cite, with its last-updated date and the date its wording was last verified.Read

Common questions

Is the score a ranking prediction?

No. The score measures how much of the best documented setup is in place, weighted by the strength of the documentation. No search engine publishes ranking weights, and the scanner's weights are not an attempt to guess them.

Why do two scans of the same site sometimes differ?

Because the site, or the ruleset, changed between them. A report records the snapshot identifier and the ruleset version it was produced with. Re-evaluating a stored snapshot with the same ruleset reproduces the report exactly; the command-line scanner keeps that snapshot for this reason.

Does it check for AI search and generative engines?

It reports which search and AI crawlers may fetch the site under its robots.txt, using each operator's own description of what the crawler does, and an AI answers readiness list: each condition Google, Microsoft or an operator documents for appearing in AI answers, and whether it is in place. It never scores those choices. Google's position is that optimizing for generative AI search is still SEO, and the technical rules apply to both. The advisory review covers the editorial side: answers, structure and the plain statement of who the site is.

Can I run it on every deploy?

Yes. The command-line scanner writes a canonical report.json, a Markdown report and the frozen snapshot, and a diff command lists new, resolved and changed findings between two reports keyed by rule, condition and URL.