@pseolint/core 0.6.5 → 0.7.0

package/README.md

@@ -1,8 +1,8 @@
 # @pseolint/core
 
-> Programmatic SEO audit engine — 45 rules, surfaced per-template, on every monitored release.
+> Programmatic SEO audit engine — 44 rules, surfaced per-template, on every monitored release.
 
-The core engine behind [pseolint](https://www.npmjs.com/package/pseolint) v0.6.2. Use this package to embed pSEO auditing into your own tools, CI pipelines, or SaaS products.
+The core engine behind [pseolint](https://www.npmjs.com/package/pseolint) v0.7.0. Use this package to embed pSEO auditing into your own tools, CI pipelines, or SaaS products.
 
 ## Install
 
@@ -34,7 +34,7 @@ for (const t of result.templates) {
 
 ## What It Checks
 
-45 rules grouped into 4 scoring super-categories (v0.4): **Integrity** (spam + content + cannibal, weight 0.50), **Discoverability** (links + tech, 0.20), **Citation** (aeo + schema, 0.25), **Data** (0.05). Source-tree namespaces remain `spam/*`, `aeo/*`, etc. for stable rule IDs.
+44 rules grouped into 4 scoring super-categories (v0.4): **Integrity** (spam + content + cannibal, weight 0.50), **Discoverability** (links + tech, 0.20), **Citation** (aeo + schema, 0.25), **Data** (0.05). Source-tree namespaces remain `spam/*`, `aeo/*`, etc. for stable rule IDs.
 
 - **Spam / SpamBrain risk** (8) — near-duplicate (SimHash), entity-swap doorways, thin content, boilerplate ratio, template diversity, template coverage, publication velocity, doorway pattern (cluster-collapsed since v0.5.2)
 - **Technical SEO** (9) — canonical consistency, canonical/noindex and robots/noindex conflicts, sitemap completeness, robots compliance, redirect chains, soft 404s, hreflang reciprocity, robots-sitemap presence, **og-completeness** (v0.5.2)

package/dist/algorithms/fact-extraction.d.ts

@@ -0,0 +1,46 @@
+import type { EntityMaskPattern, ParsedPage } from "../types.js";
+export type FactKind = "money" | "percent" | "timeframe" | "date" | "isoDate" | "form" | "ratio" | "measurement";
+export interface FactSpan {
+    value: string;
+    kind: FactKind;
+}
+export interface NamedEntity {
+    value: string;
+    source: "proper-noun" | "cue-word" | "json-ld";
+    type?: "organization" | "person" | "product" | "law" | "standard" | "place" | "other";
+}
+export interface Citation {
+    href: string;
+    domain: string;
+    authority: "authoritative" | "general";
+    reason?: "tld" | "allowlist";
+}
+export interface GroundedClaim {
+    sentence: string;
+    facts: string[];
+    citations: string[];
+}
+export interface PageFacts {
+    /** EXACTLY today's extractRawFacts() output (run on entity-masked text). Frozen. */
+    citableFacts: string[];
+    measurements: FactSpan[];
+    namedEntities: NamedEntity[];
+    citations: Citation[];
+    groundedClaims: GroundedClaim[];
+}
+export declare function extractCitableFacts(text: string): string[];
+export declare function extractMeasurements(maskedText: string): FactSpan[];
+export declare function extractNamedEntities(maskedText: string, jsonLd?: unknown[]): NamedEntity[];
+export declare const DEFAULT_CITATION_ALLOWLIST: readonly string[];
+export declare function registrableDomain(host: string): string;
+export declare function classifyCitations(resolvedHrefs: readonly string[], pageUrl: string, allowlist?: readonly string[]): Citation[];
+export declare function hasAuthoritativeCitation(resolvedHrefs: readonly string[], pageUrl: string, allowlist?: readonly string[]): boolean;
+/**
+ * Deterministic approximation of "a verifiable claim": a block (<p>/<li>) that
+ * contains a statistic AND an outbound citation. Approximated at block level,
+ * not exact sentence level — documented limitation. Detects co-occurrence, not
+ * semantic truth. Consume at `speculative` confidence.
+ */
+export declare function extractGroundedClaims(html: string, pageUrl: string, allowlist?: readonly string[]): GroundedClaim[];
+export declare function extractPageFacts(page: Pick<ParsedPage, "url" | "contentText" | "html" | "resolvedHrefs" | "jsonLd">, entityPatterns: EntityMaskPattern[], allowlist?: readonly string[]): PageFacts;
+//# sourceMappingURL=fact-extraction.d.ts.map

package/dist/algorithms/fact-extraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-extraction.d.ts","sourceRoot":"","sources":["../../src/algorithms/fact-extraction.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEjE,MAAM,MAAM,QAAQ,GAChB,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAC/D,OAAO,GAAG,aAAa,CAAC;AAE5B,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;IAC/C,IAAI,CAAC,EAAE,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;CACvF;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,eAAe,GAAG,SAAS,CAAC;IACvC,MAAM,CAAC,EAAE,KAAK,GAAG,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,oFAAoF;IACpF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,QAAQ,EAAE,CAAC;IACzB,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,cAAc,EAAE,aAAa,EAAE,CAAC;CACjC;AAqBD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAWD,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,EAAE,CAclE;AA4BD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,WAAW,EAAE,CAe9F;AAED,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAIvD,CAAC;AAWF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtD;AAMD,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAA+B,GACxD,QAAQ,EAAE,CAqBZ;AAED,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAA+B,GACxD,OAAO,CAET;AAYD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,SAAS,MAAM,EAA+B,GACxD,aAAa,EAAE,CA0BjB;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,aAAa,GAAG,MAAM,GAAG,eAAe,GAAG,QAAQ,CAAC,EACnF,cAAc,EAAE,iBAAiB,EAAE,EACnC,SAAS,GAAE,SAAS,MAAM,EAA+B,GACxD,SAAS,CASX"}

package/dist/algorithms/fact-extraction.js

@@ -0,0 +1,217 @@
+import { load } from "cheerio";
+import { maskEntities } from "./entity-mask.js";
+// --- Numeric "citable" facts: the frozen subset aeo/citable-facts counts. ---
+// These six patterns are lifted verbatim from rules/aeo/citable-facts.ts and
+// MUST stay byte-identical to preserve the calibration corpus.
+const CITABLE_FACT_PATTERNS = [
+    { name: "dollar", regex: /\$[\d,]+(\.\d{2})?/g },
+    { name: "percent", regex: /\b\d+(\.\d+)?\s*%/g },
+    {
+        name: "timeframe",
+        regex: /\b\d+(?:-\d+)?\s*(business\s+days?|days?|weeks?|months?|years?|hours?|minutes?)\b/gi,
+    },
+    {
+        name: "date",
+        regex: /\b(january|february|march|april|may|june|july|august|september|october|november|december)\s+\d{1,2}(?:,\s*\d{4})?\b/gi,
+    },
+    { name: "isoDate", regex: /\b\d{4}-\d{2}-\d{2}\b/g },
+    { name: "form", regex: /\bForm\s+[A-Z0-9][A-Z0-9-]*\b/g },
+];
+export function extractCitableFacts(text) {
+    const out = new Set();
+    for (const { regex } of CITABLE_FACT_PATTERNS) {
+        const matches = text.match(regex);
+        if (!matches)
+            continue;
+        for (const m of matches)
+            out.add(m.trim().toLowerCase());
+    }
+    return Array.from(out);
+}
+// --- Measurements: NEW numeric kinds, deliberately separate from citableFacts. ---
+const MEASUREMENT_UNITS = "kg|g|lb|lbs|oz|mi|km|cm|mm|ft|in|MB|GB|TB|KB|ms|fps|mph|kWh";
+const MEASUREMENT_PATTERNS = [
+    { kind: "ratio", regex: /\b\d+(?:\.\d+)?\s*(?:out of|in)\s*\d+\b/gi },
+    { kind: "ratio", regex: /\b\d+\s*:\s*\d+\b/g },
+    { kind: "measurement", regex: new RegExp(`\\b\\d+(?:\\.\\d+)?\\s*(?:${MEASUREMENT_UNITS})\\b`, "g") },
+];
+export function extractMeasurements(maskedText) {
+    const seen = new Set();
+    const out = [];
+    for (const { kind, regex } of MEASUREMENT_PATTERNS) {
+        const matches = maskedText.match(regex);
+        if (!matches)
+            continue;
+        for (const m of matches) {
+            const value = m.replace(/\s+/g, " ").trim().toLowerCase();
+            if (seen.has(value))
+                continue;
+            seen.add(value);
+            out.push({ value, kind });
+        }
+    }
+    return out;
+}
+const MULTI_WORD_PROPER_NOUN = /\b[A-Z][a-z]+(?:\s+(?:of\s+|de\s+|and\s+|the\s+)?[A-Z][a-z]+)+\b/g;
+const ACRONYM = /\b(?:ISO|GDPR|HIPAA|FDA|SEC|FTC|EPA|W3C|IETF|RFC|NIST|OSHA|IRS|EU|UN|WHO|CCPA|PCI)\b/g;
+const CUE_WORD = /\b(?:Inc|LLC|Ltd|Corp|GmbH|Act|Regulation|Directive|Agency|Department|Bureau|Commission|Authority|University|Institute|Association|Standard|Protocol)\b/;
+const JSON_LD_ENTITY_TYPES = new Set([
+    "Organization", "GovernmentOrganization", "Corporation", "NGO",
+    "Person", "Product", "Brand",
+]);
+function jsonLdEntities(nodes) {
+    const out = [];
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            node.forEach(visit);
+            return;
+        }
+        if (typeof node !== "object" || node === null)
+            return;
+        const obj = node;
+        const type = obj["@type"];
+        const name = obj["name"];
+        if (typeof name === "string" && typeof type === "string" && JSON_LD_ENTITY_TYPES.has(type)) {
+            out.push({ value: name.trim().toLowerCase(), source: "json-ld", type: "organization" });
+        }
+        for (const v of Object.values(obj))
+            visit(v);
+    };
+    nodes.forEach(visit);
+    return out;
+}
+export function extractNamedEntities(maskedText, jsonLd = []) {
+    const seen = new Set();
+    const out = [];
+    const push = (value, source) => {
+        const v = value.replace(/\s+/g, " ").trim().toLowerCase();
+        if (v.length < 2 || seen.has(v))
+            return;
+        seen.add(v);
+        out.push({ value: v, source });
+    };
+    for (const m of jsonLdEntities(jsonLd))
+        push(m.value, "json-ld");
+    for (const m of maskedText.match(ACRONYM) ?? [])
+        push(m, "cue-word");
+    for (const m of maskedText.match(MULTI_WORD_PROPER_NOUN) ?? []) {
+        push(m, CUE_WORD.test(m) ? "cue-word" : "proper-noun");
+    }
+    return out;
+}
+export const DEFAULT_CITATION_ALLOWLIST = [
+    "wikipedia.org", "w3.org", "iso.org", "ietf.org", "rfc-editor.org",
+    "doi.org", "nih.gov", "ncbi.nlm.nih.gov", "who.int", "schema.org",
+    "oecd.org", "worldbank.org", "europa.eu",
+];
+const MULTI_PART_SUFFIXES = new Set([
+    "co.uk", "ac.uk", "gov.uk", "org.uk", "com.au", "gov.au", "edu.au",
+    "co.jp", "co.nz", "co.za", "com.br",
+]);
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+export function registrableDomain(host) {
+    const labels = host.replace(/^www\./, "").split(".");
+    if (labels.length <= 2)
+        return labels.join(".");
+    const lastTwo = labels.slice(-2).join(".");
+    if (MULTI_PART_SUFFIXES.has(lastTwo))
+        return labels.slice(-3).join(".");
+    return lastTwo;
+}
+function isAuthoritativeTld(host) {
+    return /\.(?:gov|edu|mil|int)$/.test(host) || /\.(?:gov|edu|ac)\.[a-z]{2}$/.test(host);
+}
+export function classifyCitations(resolvedHrefs, pageUrl, allowlist = DEFAULT_CITATION_ALLOWLIST) {
+    const pageHost = hostOf(pageUrl);
+    const pageDomain = pageHost ? registrableDomain(pageHost) : null;
+    const seen = new Set();
+    const out = [];
+    for (const href of resolvedHrefs) {
+        const host = hostOf(href);
+        if (!host)
+            continue;
+        const domain = registrableDomain(host);
+        if (pageDomain && domain === pageDomain)
+            continue; // internal link
+        if (seen.has(href))
+            continue;
+        seen.add(href);
+        if (isAuthoritativeTld(host)) {
+            out.push({ href, domain, authority: "authoritative", reason: "tld" });
+        }
+        else if (allowlist.some((d) => host === d || host.endsWith(`.${d}`))) {
+            out.push({ href, domain, authority: "authoritative", reason: "allowlist" });
+        }
+        else {
+            out.push({ href, domain, authority: "general" });
+        }
+    }
+    return out;
+}
+export function hasAuthoritativeCitation(resolvedHrefs, pageUrl, allowlist = DEFAULT_CITATION_ALLOWLIST) {
+    return classifyCitations(resolvedHrefs, pageUrl, allowlist).some((c) => c.authority === "authoritative");
+}
+const SENTENCE_SPLIT = /(?<=[.!?])\s+(?=[A-Z0-9"'(])/;
+function resolveHrefs(hrefs, base) {
+    const out = [];
+    for (const h of hrefs) {
+        try {
+            out.push(new URL(h, base).href);
+        }
+        catch { /* skip unparseable */ }
+    }
+    return out;
+}
+/**
+ * Deterministic approximation of "a verifiable claim": a block (<p>/<li>) that
+ * contains a statistic AND an outbound citation. Approximated at block level,
+ * not exact sentence level — documented limitation. Detects co-occurrence, not
+ * semantic truth. Consume at `speculative` confidence.
+ */
+export function extractGroundedClaims(html, pageUrl, allowlist = DEFAULT_CITATION_ALLOWLIST) {
+    const $ = load(html);
+    $("nav, header, footer, aside, script, style, noscript").remove();
+    const claims = [];
+    const scope = $("article").length > 0 ? $("article") : $("main").length > 0 ? $("main") : $("body");
+    scope.find("p, li").each((_i, el) => {
+        const $el = $(el);
+        const rawLinks = $el.find("a[href]").map((_j, a) => String($(a).attr("href") ?? "")).get();
+        const citations = classifyCitations(resolveHrefs(rawLinks, pageUrl), pageUrl, allowlist);
+        if (citations.length === 0)
+            return;
+        const text = $el.text().replace(/\s+/g, " ").trim();
+        for (const sentence of text.split(SENTENCE_SPLIT)) {
+            const facts = [
+                ...extractCitableFacts(sentence),
+                ...extractMeasurements(sentence).map((m) => m.value),
+            ];
+            if (facts.length === 0)
+                continue;
+            claims.push({
+                sentence: sentence.trim().slice(0, 240),
+                facts,
+                citations: citations.map((c) => c.href),
+            });
+            break; // one grounded claim per block is enough; avoids over-counting
+        }
+    });
+    return claims;
+}
+export function extractPageFacts(page, entityPatterns, allowlist = DEFAULT_CITATION_ALLOWLIST) {
+    const masked = maskEntities(page.contentText, entityPatterns);
+    return {
+        citableFacts: extractCitableFacts(masked),
+        measurements: extractMeasurements(masked),
+        namedEntities: extractNamedEntities(masked, page.jsonLd),
+        citations: classifyCitations(page.resolvedHrefs, page.url, allowlist),
+        groundedClaims: extractGroundedClaims(page.html, page.url, allowlist),
+    };
+}
+//# sourceMappingURL=fact-extraction.js.map

package/dist/algorithms/fact-extraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-extraction.js","sourceRoot":"","sources":["../../src/algorithms/fact-extraction.ts"],"names":[],"mappings":"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"}

package/dist/auditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"AAmEA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGZ,WAAW,EAUX,UAAU,EAIX,MAAM,YAAY,CAAC;AAQpB,OAAO,EAA8D,KAAK,kBAAkB,EAAiB,MAAM,sBAAsB,CAAC;AA+D1I,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEvE;AA6xBD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,UAAU,EAAE,EACtB,cAAc,EAAE,kBAAkB,GAAG,SAAS,GAC7C,UAAU,EAAE,CAed;AAoYD,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBjG;AAsoBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAirC/F"}
+{"version":3,"file":"auditor.d.ts","sourceRoot":"","sources":["../src/auditor.ts"],"names":[],"mappings":"AAoEA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGZ,WAAW,EAUX,UAAU,EAIX,MAAM,YAAY,CAAC;AAQpB,OAAO,EAA8D,KAAK,kBAAkB,EAAiB,MAAM,sBAAsB,CAAC;AAiE1I,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEvE;AA2yBD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,UAAU,EAAE,EACtB,cAAc,EAAE,kBAAkB,GAAG,SAAS,GAC7C,UAAU,EAAE,CAed;AAoYD,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBjG;AA+pBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAgxC/F"}

package/dist/auditor.js

@@ -5,6 +5,7 @@ import { parseHtmlPage } from "./parser.js";
 import { pageSkipReason } from "./page-filter.js";
 import { mergeNormalizeUrlOptions, normalizeAuditUrl } from "./url-normalize.js";
 import { eeatSignalsRule } from "./rules/content/eeat-signals.js";
+import { citationCoverageRule } from "./rules/content/citation-coverage.js";
 import { metaUniquenessRule } from "./rules/content/meta-uniqueness.js";
 import { missingAuthorRule } from "./rules/content/missing-author.js";
 import { uniqueValueRule } from "./rules/content/unique-value.js";
@@ -84,6 +85,8 @@ const DEFAULTS = {
     metaUniquenessMinJaccard: 0.9,
     linkDepthMaxClicks: 3,
     templateCoverageMinPages: 5,
+    citationCoverageMinClaims: 4,
+    citationCoverageMinAuthoritative: 1,
     answerFirstMaxWords: 100,
     citableFactsMin: 3,
     citableFactsTarget: 8,
@@ -414,6 +417,9 @@ const RULE_IMPACTS = {
     "content/title-uniqueness": { baseImpact: 8, perInstance: 2, maxImpact: 25 }, // 2026-05-03 round 11: title is high-impact but the original 50-cap was disproportionate to other content rules and tipped Typeform into critical on a 6-finding cluster. Keep the rule at native error severity (duplicate titles ARE real bugs); just don't let one rule dominate the integrity bucket.
     "content/heading-structure": { baseImpact: 5, perInstance: 1, maxImpact: 20 },
     "content/image-alt-text": { baseImpact: 3, perInstance: 1, maxImpact: 20 },
+    // Citation coverage is low-confidence (block-level grounded-claim heuristic);
+    // keep its impact modest so it nudges rather than dominates the score.
+    "content/citation-coverage": { baseImpact: 3, perInstance: 1, maxImpact: 15 },
     "content/translation-no-op": { baseImpact: 30, perInstance: 10, maxImpact: 60 },
     // v1 warning-severity heuristic; lower than translation-no-op since it's speculative
     "content/regurgitated-content": { baseImpact: 15, perInstance: 5, maxImpact: 35 },
@@ -653,6 +659,13 @@ sampled = false) {
     if (isEnabled("content/eeat-signals") && modeOk("content/eeat-signals")) {
         pushAll(findings, tag(eeatSignalsRule(pages)));
     }
+    if (isEnabled("content/citation-coverage") && modeOk("content/citation-coverage")) {
+        pushAll(findings, tag(citationCoverageRule(pages, entityPatterns, {
+            minClaims: resolvedRules.citationCoverageMinClaims,
+            minAuthoritative: resolvedRules.citationCoverageMinAuthoritative,
+            allowlist: resolvedRules.citationAllowlist,
+        })));
+    }
     // 2026-05-03 v0.5.2 blind-spot fixes — title uniqueness + heading
     // structure + image alt-text were tier-1 gaps in the blind-spot audit.
     if (isEnabled("content/title-uniqueness") && modeOk("content/title-uniqueness")) {
@@ -1249,36 +1262,46 @@ async function collectUrlsFromSitemap(sitemapText, sitemapUrl, visited, timeoutM
                 lastmodByUrl.set(entry.url, entry.lastmod);
             }
         }
-        return { urls, lastmodByUrl };
+        return { urls, lastmodByUrl, childTotal: 0, childFailed: 0 };
     }
-    // It's a sitemap index. Stop recursing past the depth cap (the index itself
-    // carries no page URLs, only child-sitemap refs, so returning empty is safe).
+    // It's a sitemap index. Past the depth cap we stop recursing — but the
+    // children we DON'T walk are unreached coverage, so report them as failed.
     if (depth >= maxDepth) {
         // eslint-disable-next-line no-console
         console.error(`pseolint: sitemap-index nesting exceeded depth ${maxDepth} at ${sitemapUrl}; not recursing further.`);
-        return { urls: [], lastmodByUrl: new Map() };
+        return { urls: [], lastmodByUrl: new Map(), childTotal: entries.length, childFailed: entries.length };
     }
     const allUrls = [];
     const allLastmodByUrl = new Map();
+    let childTotal = 0;
+    let childFailed = 0;
     for (const entry of entries) {
         const childUrl = entry.url;
         if (signal?.aborted)
             throw signal.reason ?? new Error("aborted");
+        childTotal += 1;
         if (visited.has(childUrl))
-            continue;
+            continue; // already walked (cyclic index) — not a failure
         const child = await fetchWithRetry(childUrl, timeoutMs, cache, stats, signal, validateHop, SITEMAP_MAX_BYTES);
-        if (!child)
+        if (!child) {
+            childFailed += 1;
             continue;
+        }
         const childLike = child.contentType.includes("xml") || looksLikeSitemap(child.text);
-        if (!childLike)
+        if (!childLike) {
+            childFailed += 1;
             continue;
-        const { urls: childUrls, lastmodByUrl: childLastmodByUrl } = await collectUrlsFromSitemap(child.text, childUrl, visited, timeoutMs, cache, stats, signal, validateHop, depth + 1, maxDepth);
+        }
+        const { urls: childUrls, lastmodByUrl: childLastmodByUrl, childTotal: ct, childFailed: cf } = await collectUrlsFromSitemap(child.text, childUrl, visited, timeoutMs, cache, stats, signal, validateHop, depth + 1, maxDepth);
         pushAll(allUrls, childUrls);
         for (const [u, lm] of childLastmodByUrl) {
             allLastmodByUrl.set(u, lm);
         }
+        // Accumulate nested index structure (a child that is itself an index).
+        childTotal += ct;
+        childFailed += cf;
     }
-    return { urls: allUrls, lastmodByUrl: allLastmodByUrl };
+    return { urls: allUrls, lastmodByUrl: allLastmodByUrl, childTotal, childFailed };
 }
 async function fetchRobotsMeta(origin, timeoutMs, cache, stats, signal, validateHop) {
     if (!origin)
@@ -1380,7 +1403,7 @@ pageSink) {
         const isXml = (contentType.includes("xml") || looksLikeSitemap(text)) && sourceStatus !== -1;
         if (isXml) {
             const visited = new Set();
-            const { urls: allSitemapUrls, lastmodByUrl: sitemapLastmodByUrl } = await collectUrlsFromSitemap(text, source, visited, timeoutMs, cache, stats, signal, validateHop);
+            const { urls: allSitemapUrls, lastmodByUrl: sitemapLastmodByUrl, childTotal: sitemapChildTotal, childFailed: sitemapChildFailed } = await collectUrlsFromSitemap(text, source, visited, timeoutMs, cache, stats, signal, validateHop);
             // If we have a budget, sample from sitemap URLs before fetching
             const sampledUrls = discoveryBudget > 0 && allSitemapUrls.length > discoveryBudget
                 ? fisherYatesSample(allSitemapUrls, discoveryBudget)
@@ -1516,7 +1539,7 @@ pageSink) {
                     });
                 }
             }
-            return { pages, sitemapUrls: new Set(allSitemapUrls), sitemapLastmodByUrl, discoveredUrlCount: allSitemapUrls.length, scrapePlan };
+            return { pages, sitemapUrls: new Set(allSitemapUrls), sitemapLastmodByUrl, discoveredUrlCount: allSitemapUrls.length, declaredSitemapUrlCount: allSitemapUrls.length, sitemapChildTotal, sitemapChildFailed, scrapePlan };
         }
         if (contentType.includes("html") || looksLikeHtml(text)) {
             const initialPage = { url: source, html: text };
@@ -1535,6 +1558,14 @@ pageSink) {
                 const knownCrawled = new Set([source]);
                 const allDiscoveredUrls = new Set([source]);
                 const maxDepth = 3;
+                // Total URLs the discovered sitemap(s) declare — the basis for the
+                // caller's coverage guardrail. Undefined when no sitemap is found.
+                let declaredSitemapUrlCount;
+                // Child-sitemap reachability for the guardrail: how many child sitemaps
+                // an index referenced vs how many we could not fetch/parse. childFailed>0
+                // means the declared URL list is itself incomplete.
+                let sitemapChildTotal = 0;
+                let sitemapChildFailed = 0;
                 // Sitemap-first discovery (like Google). Before link-crawling, read the
                 // sitemap(s) the site declares — link-crawl only reaches *linked* pages,
                 // but a pSEO site's whole point is thousands of programmatic URLs that
@@ -1574,13 +1605,19 @@ pageSink) {
                         }
                         if (!(smType.includes("xml") || looksLikeSitemap(smText)))
                             continue;
-                        const { urls: discoveredSmUrls } = await collectUrlsFromSitemap(smText, candidate, visitedSitemaps, timeoutMs, cache, stats, signal, validateHop);
+                        const { urls: discoveredSmUrls, childTotal: ct, childFailed: cf } = await collectUrlsFromSitemap(smText, candidate, visitedSitemaps, timeoutMs, cache, stats, signal, validateHop);
+                        sitemapChildTotal += ct;
+                        sitemapChildFailed += cf;
                         pushAll(sitemapListedUrls, discoveredSmUrls);
                         // When probing the conventional paths, stop at the first that hits.
                         if (probing && discoveredSmUrls.length > 0)
                             break;
                     }
                     // Same-origin + robots-aware filter, deduped against what we have.
+                    // Record what the sitemap(s) declared (deduped) before same-origin /
+                    // robots filtering — the operator's site has this many URLs.
+                    if (sitemapListedUrls.length > 0)
+                        declaredSitemapUrlCount = new Set(sitemapListedUrls).size;
                     const seedUrls = Array.from(new Set(sitemapListedUrls)).filter((u) => {
                         if (knownCrawled.has(u))
                             return false;
@@ -1686,7 +1723,7 @@ pageSink) {
                     if (newPages.length === 0)
                         break;
                 }
-                return { pages, discoveredUrlCount: allDiscoveredUrls.size };
+                return { pages, discoveredUrlCount: allDiscoveredUrls.size, declaredSitemapUrlCount, sitemapChildTotal, sitemapChildFailed };
             }
             return { pages };
         }
@@ -1780,6 +1817,7 @@ export async function auditSource(source, options) {
     // surfaced on the summary instead.
     let truncated = false;
     let truncatedReason;
+    let truncatedKind;
     const signal = composeSignals(externalSignal, backpressureAbort.signal);
     const observer = new FetchObserver();
     // 2026-05-03 calibration: the prior (3s p95 cap, 2× baseline multiplier)
@@ -1830,6 +1868,7 @@ export async function auditSource(source, options) {
             return false;
         truncated = true;
         truncatedReason = backpressureError.message;
+        truncatedKind = "backpressure";
         return true;
     }
     function throwIfAborted() {
@@ -1861,6 +1900,9 @@ export async function auditSource(source, options) {
         metaUniquenessMinJaccard: options?.rules?.metaUniquenessMinJaccard ?? DEFAULTS.metaUniquenessMinJaccard,
         linkDepthMaxClicks: options?.rules?.linkDepthMaxClicks ?? DEFAULTS.linkDepthMaxClicks,
         templateCoverageMinPages: options?.rules?.templateCoverageMinPages ?? DEFAULTS.templateCoverageMinPages,
+        citationCoverageMinClaims: options?.rules?.citationCoverageMinClaims ?? DEFAULTS.citationCoverageMinClaims,
+        citationCoverageMinAuthoritative: options?.rules?.citationCoverageMinAuthoritative ?? DEFAULTS.citationCoverageMinAuthoritative,
+        citationAllowlist: options?.rules?.citationAllowlist,
         answerFirstMaxWords: options?.rules?.answerFirstMaxWords ?? DEFAULTS.answerFirstMaxWords,
         citableFactsMin: options?.rules?.citableFactsMin ?? DEFAULTS.citableFactsMin,
         citableFactsTarget: options?.rules?.citableFactsTarget ?? DEFAULTS.citableFactsTarget,
@@ -1952,6 +1994,9 @@ export async function auditSource(source, options) {
     let sitemapUrlSet;
     let sitemapLastmodByUrl;
     let discoveredUrlCount;
+    let declaredSitemapUrlCount;
+    let sitemapChildTotal;
+    let sitemapChildFailed;
     let scrapePlan;
     if (hasPinnedUrlsEarly) {
         const pinned = options.pinnedUrls;
@@ -2041,6 +2086,9 @@ export async function auditSource(source, options) {
             sitemapUrlSet = loaded.sitemapUrls;
             sitemapLastmodByUrl = loaded.sitemapLastmodByUrl;
             discoveredUrlCount = loaded.discoveredUrlCount;
+            declaredSitemapUrlCount = loaded.declaredSitemapUrlCount;
+            sitemapChildTotal = loaded.sitemapChildTotal;
+            sitemapChildFailed = loaded.sitemapChildFailed;
             scrapePlan = loaded.scrapePlan;
         }
         catch (err) {
@@ -2053,6 +2101,7 @@ export async function auditSource(source, options) {
                 if (!salvageBackpressure()) {
                     truncated = true;
                     truncatedReason = err.message;
+                    truncatedKind = "backpressure";
                 }
                 // Recover whatever was fetched before the abort. The sink is the same
                 // array loadPagesFromSource was pushing into, so it holds the partial
@@ -2063,6 +2112,9 @@ export async function auditSource(source, options) {
                 sitemapUrlSet = undefined;
                 sitemapLastmodByUrl = undefined;
                 discoveredUrlCount = undefined;
+                declaredSitemapUrlCount = undefined;
+                sitemapChildTotal = undefined;
+                sitemapChildFailed = undefined;
                 scrapePlan = undefined;
             }
             else {
@@ -2070,6 +2122,12 @@ export async function auditSource(source, options) {
             }
         }
     }
+    // Pages we successfully FETCHED (HTTP 2xx) from discovery — before content-type
+    // and policy filtering, and before sampling. This is the right denominator for
+    // the coverage guardrail: noindex / non-HTML pages were still *reached* (they
+    // count), intentional sampling happens later (doesn't count against us), and
+    // only genuinely-unreachable URLs (4xx/5xx) are missing from it.
+    const fetchedCount = loadedPagesRaw.length;
     // The scrapePlan tells us which URLs were skipped pre-fetch under monitoring
     // mode. Surface them in skippedUrls so they show up under summary.skippedUrls
     // (kept for back-compat with --since consumers); T7 will carry their prior
@@ -2103,7 +2161,10 @@ export async function auditSource(source, options) {
             skippedByContentType.push(p.url);
         }
     }
-    loadedPages.splice(0, loadedPages.length, ...htmlOnlyPages);
+    // Replace contents in place without `splice(0, n, ...big)` — that spread hits
+    // the V8 argument-count cap on large corpora (same class as pushAll).
+    loadedPages.length = 0;
+    pushAll(loadedPages, htmlOnlyPages);
     if (discoveredUrlCount && discoveredUrlCount > loadedPages.length) {
         console.error(`Discovered ${discoveredUrlCount} pages, fetched ${loadedPages.length} for audit. Use --sample-size 0 for full crawl.`);
     }
@@ -2261,9 +2322,21 @@ export async function auditSource(source, options) {
     const guardedClassification = applyDegenerationGuard(computedClassification, corpusStatsFromPages(parsedPages));
     // `--strict` (or AuditOptions.strict) keeps the classification but forces
     // every rule to run regardless of detected site type.
+    //
+    // A backpressure abort BEFORE classification salvages only a fragment of the
+    // crawl (`truncated` is already set here; the coverage guardrail runs later).
+    // Classifying that fragment — e.g. the 1 page left after the watchdog aborts a
+    // cold-start origin — as `small-marketing` and suppressing the pSEO rules off
+    // it is exactly what produced the confident false "READY" on a 5,600-page
+    // site. When the run was truncated pre-classification we genuinely could not
+    // determine the site type: force `unclear` (confidence 0, no suppression,
+    // neutral scoring) so nothing masks the incompleteness.
+    const classificationUnreliable = truncated;
     const siteClassification = options?.strict
         ? { ...guardedClassification, suppressedRules: [] }
-        : guardedClassification;
+        : classificationUnreliable
+            ? { ...guardedClassification, type: "unclear", confidence: 0, suppressedRules: [] }
+            : guardedClassification;
     const suppressedRuleSet = new Set(siteClassification.suppressedRules);
     // Classify pages into groups and run only enabled rules per group
     const classified = classifyPages(parsedPages, options?.pageGroups);
@@ -2478,9 +2551,66 @@ export async function auditSource(source, options) {
     // salvaged whatever pages had been fetched. Consumers MUST treat coverage as
     // a lower bound (counts/verdict are partial). Only set when actually
     // truncated so complete runs keep `truncated` absent.
+    // ── Coverage guardrails (#4) ─────────────────────────────────────────────
+    // A sitemap was found at discovery, so we know roughly how large the site is.
+    // Two independent under-coverage signals, each reusing the `truncated`
+    // partial-coverage surface (CLI/Action/MCP/web already flag it) tagged
+    // `truncatedKind: "coverage"` so consumers can tell it apart from a
+    // backpressure abort. Backpressure (set during the crawl) takes precedence.
+    if (!truncated && sitemapChildFailed && sitemapChildFailed > 0) {
+        // (A) Extraction-side: a sitemap INDEX referenced child sitemaps we could
+        // not fetch/parse (404, non-sitemap, or beyond the depth cap). The declared
+        // URL list is itself incomplete — the "unreachable child sitemaps" case a
+        // urls-only count can never see (and the original false-negative class).
+        truncated = true;
+        truncatedKind = "coverage";
+        truncatedReason =
+            `${sitemapChildFailed} of ${sitemapChildTotal} child sitemaps referenced by the sitemap index could not be ` +
+                `fetched or parsed — both the declared URL count and this audit are incomplete, so the verdict is not ` +
+                `representative of the full site. Check that every child sitemap is reachable (HTTP 200, valid XML).`;
+        // eslint-disable-next-line no-console
+        console.error(`pseolint: ${truncatedReason}`);
+    }
+    if (!truncated && declaredSitemapUrlCount && declaredSitemapUrlCount >= 20) {
+        // (B) Audit-side: the sitemap declared N URLs but we FETCHED far fewer than
+        // we intended to. Compare against `fetchedCount` (pages actually fetched,
+        // pre-filter/pre-sample) so legitimately-skipped pages (noindex, non-HTML)
+        // and intentional sampling do NOT register as a shortfall. `intended` is
+        // bounded by every deliberate limit — an explicit sample, the crawl cap, and
+        // the declared total — so none of them false-fire.
+        const sampleCap = sampleSize > 0 ? sampleSize : Number.POSITIVE_INFINITY;
+        const crawlCap = maxCrawlDiscovered > 0 ? maxCrawlDiscovered : Number.POSITIVE_INFINITY;
+        const intended = Math.min(sampleCap, crawlCap, declaredSitemapUrlCount);
+        const floor = Math.max(20, Math.floor(intended * 0.05));
+        // `intended >= 20`: only judge representativeness when we actually meant to
+        // audit a substantial slice. A deliberately tiny sample/crawl cap (intended
+        // < 20) is the operator's choice, not under-discovery — don't flag it (and
+        // it would otherwise trip the absolute floor of 20).
+        if (intended >= 20 && fetchedCount < floor) {
+            const unreached = Math.max(0, declaredSitemapUrlCount - fetchedCount);
+            const ratio = fetchedCount / declaredSitemapUrlCount;
+            const pct = (ratio * 100).toFixed(ratio < 0.01 ? 2 : 1);
+            truncated = true;
+            truncatedKind = "coverage";
+            truncatedReason =
+                `Fetched ${fetchedCount} of ~${declaredSitemapUrlCount} sitemap-declared URLs (~${pct}% coverage); ` +
+                    `~${unreached} could not be retrieved (4xx/5xx, redirects, or robots-blocked). The verdict covers only the ` +
+                    `pages reached and is not representative — check for a stale sitemap or unreachable pages, or raise crawl limits.`;
+            // eslint-disable-next-line no-console
+            console.error(`pseolint: ${truncatedReason}`);
+        }
+    }
     if (truncated) {
         summary.truncated = true;
         summary.truncatedReason = truncatedReason;
+        if (truncatedKind)
+            summary.truncatedKind = truncatedKind;
+        // A truncated run is incomplete — never present it as a clean green. Floor
+        // the verdict to at least "caution" so the headline matches the partial-
+        // coverage banner instead of the false "READY ✓" over a salvaged fragment.
+        // ("ready" is the only rung below "caution"; everything else already is.)
+        if (summary.verdict === "ready")
+            summary.verdict = "caution";
     }
     if (cacheConfig) {
         summary.cacheStats = cacheStats;