The gap
Issue #16 renamed llms-txt-freshness to llms-txt-coverage, and that rename was right: comparing the llms.txt link set against the sitemap catches coverage gaps and orphaned entries, but it can't tell you whether the file is fresh — whether what it says about each page still matches the page. A file can pass coverage perfectly and still describe last quarter's site.
That distinction matters because staleness is the documented failure mode for machine-shaped alternate versions. The web has run this experiment before: WCAG 1.0 (1999) required alternate accessible pages to be "updated as often as the inaccessible (original) page," and its note explains why — "alternative pages are generally updated less often than 'primary' pages. An out-of-date page may be as frustrating as one that is inaccessible." The requirement was in the spec, and drift happened anyway, because nothing made it checkable.
Proposed check: verifiable same-deploy provenance
Two properties, both mechanically checkable by any consumer in two fetches:
- Build identity. The site emits a per-build identifier into llms.txt (a
Build: line) and into every page (<meta name="build-id">). Equal values prove the file and the page shipped in the same atomic deploy — drift between them is structurally impossible, not just unlikely.
- Content equality. Each llms.txt entry's description is the linked page's own meta description, so any single line can be spot-checked: fetch the page, compare strings.
Live implementation
Running now at feather.ca/llms.txt — the file's provenance block states both checks, and you can verify them against any page it links to. The site is Eleventy on Netlify; the build id is a UTC timestamp + commit sha, emitted from one data file into both surfaces. A Node verifier that runs all checks (build-id equality on every linked page + description equality per section) exists and I'd be glad to adapt it as an afdocs check.
Happy to help spec this in whatever form fits — new check alongside llms-txt-coverage, or an optional tier of it.
This proposal was drafted and filed by Ellis, my AI agent, on my behalf — fittingly, Ellis is also the agent that generates and maintains the llms.txt file in question. I review and respond to replies personally. — Derek
The gap
Issue #16 renamed
llms-txt-freshnesstollms-txt-coverage, and that rename was right: comparing the llms.txt link set against the sitemap catches coverage gaps and orphaned entries, but it can't tell you whether the file is fresh — whether what it says about each page still matches the page. A file can pass coverage perfectly and still describe last quarter's site.That distinction matters because staleness is the documented failure mode for machine-shaped alternate versions. The web has run this experiment before: WCAG 1.0 (1999) required alternate accessible pages to be "updated as often as the inaccessible (original) page," and its note explains why — "alternative pages are generally updated less often than 'primary' pages. An out-of-date page may be as frustrating as one that is inaccessible." The requirement was in the spec, and drift happened anyway, because nothing made it checkable.
Proposed check: verifiable same-deploy provenance
Two properties, both mechanically checkable by any consumer in two fetches:
Build:line) and into every page (<meta name="build-id">). Equal values prove the file and the page shipped in the same atomic deploy — drift between them is structurally impossible, not just unlikely.Live implementation
Running now at feather.ca/llms.txt — the file's provenance block states both checks, and you can verify them against any page it links to. The site is Eleventy on Netlify; the build id is a UTC timestamp + commit sha, emitted from one data file into both surfaces. A Node verifier that runs all checks (build-id equality on every linked page + description equality per section) exists and I'd be glad to adapt it as an afdocs check.
Happy to help spec this in whatever form fits — new check alongside
llms-txt-coverage, or an optional tier of it.This proposal was drafted and filed by Ellis, my AI agent, on my behalf — fittingly, Ellis is also the agent that generates and maintains the llms.txt file in question. I review and respond to replies personally. — Derek