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):

1. Visible dates: detect on-page "Published" / "Updated on" / "Last reviewed" patterns and their values (ISO or human-readable).
2. Schema dates: parse datePublished/dateModified from JSON-LD Article/BlogPosting/NewsArticle.
3. Agreement: visible date and schema date must match; flag mismatches and schema dates with no visible counterpart (AI engines distrust hidden-only dates).
4. 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.
5. 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.

Verification

• dom_assert: visible date string present and parses; matches schema value.
• schema_validator: datePublished/dateModified present, valid ISO 8601, dateModified >= datePublished.
• header_check: HTTP Last-Modified header corroborates the claimed modification date.
• When the live tier (header fetch / validator) is unavailable, status is needs_api, never a false pass.

Findings

Findings conform to schema/finding.schema.json; axis both; confidence directional throughout. Severity policy: 5 is reserved for catastrophic, eligibility-killing facts at site/template scope; 4 major · 3 moderate · 2 minor · 1 cosmetic · 0 informational — and only an established severity-5 fail in an active category can cap a score (references/scoring-model.md). Freshness never caps.

• M13.datemodified.missing — Article schema with datePublished but no dateModified (fail, severity 3, fixable: auto).
• M13.dates.visible_schema_mismatch — visible "Updated May 2025" against schema dateModified: 2023-01-10 (warn, severity 3, fixable: proposed).
• M13.content.stale_volatile — a "best X 2024" page unchanged for two years on a fast-moving topic (warn, severity 2, fixable: advisory).
• M13.schema.date_unparseable — a date field that exists but does not parse as ISO 8601, or a page with several dateModified values (the latest wins, and the conflict is reported) (warn, severity 2, fixable: proposed). Emit this instead of a mismatch: an unreadable date is a parsing gap, not proof the dates disagree. Each finding: evidence.observed quotes the page (date string + selector); verification.reproduce is a runnable assertion (e.g. node "${CLAUDE_PLUGIN_ROOT}/scripts/check-freshness.mjs" --snapshot <pages/<slug>.json> [--lang en|es|auto] (or --url <u>)); expected_impact is banded + confidence-tagged, with any published number confined to rationale with a citation.

Honesty

• Freshness is a contextual signal, not a universal ranking boost — refreshing evergreen content rarely moves rankings, and a dateModified bump without a real content change is detectable and adds no durable value. Confidence here is directional, never established; never present a date edit as a guaranteed ranking gain or backdate to fake recency.
• Date parsing is language-bound: Spanish month names and article:published_time/article:modified_time are read, but an unrecognized format produces M13.schema.date_unparseable, never a fabricated mismatch.