seo-freshness (M13)

Freshness is a recency signal both classic ranking systems (Query Deserves Freshness) and AI answer engines weigh — Perplexity in particular favours recently-updated sources when citing. Date fields tie directly to Article schema (cross-check M5); see references/schema-tier1.md for the date rules.

Inputs

Work from the PageSnapshot named in your dispatch envelope: read parsed from <run_dir>/pages/<slug>.json (jsonld[], metas[] for article:published_time/modified_time) plus headers.last-modified; Grep pages/<slug>.html for verbatim evidence; site artifacts live in <run_dir>/site/{robots.json,sitemaps.json,discovery.json}. Deterministic findings already emitted by audit.mjs are listed in <run_dir>/findings.deterministic.json — do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs" and use the printed snapshot path.

Audits

Working from the PageSnapshot (parsed_rendered when render.used is not none, else parsed):

Visible dates: detect on-page "Published" / "Updated on" / "Last reviewed" patterns and their values (ISO or human-readable).
Schema dates: parse datePublished/dateModified from JSON-LD Article/BlogPosting/NewsArticle.
Agreement: visible date and schema date must match; flag mismatches and schema dates with no visible counterpart (AI engines distrust hidden-only dates).
Staleness: estimate content age (most recent reliable date) vs topic volatility — fast-moving topics (prices, tooling, "best X 2026", regulations) decay faster than evergreen reference content. Report stale, not just old.
Pattern hygiene: "updated on" with no substantive content change is a freshness anti-pattern — note it, never recommend it.

Fixes

AUTO (fixable: auto): inject a missing dateModified into existing Article schema as an additive diff for fix. Never backdate to a false date — use the verifiable last-change date (e.g. Last-Modified header / repo mtime / today) or leave a clearly-marked TODO placeholder the user confirms.
PROPOSED (fixable: proposed): surface visible-vs-schema date mismatches with the corrected value as a draft requiring per-item accept; never auto-rewrite a date the user must verify.
ADVISORY (fixable: advisory): recommend a genuine content refresh for stale-on-volatile pages — the tool never writes editorial content. Never fabricate dates or invent an update that did not happen.