seo-drift

Family: seo Status: Stable

Purpose

Baseline + diff for SEO state — "git for SEO." Capture a page's SEO-critical elements, store the snapshot, then after a deploy or content change diff a fresh capture against the stored baseline to catch silent regressions before they cost rankings. Two modes: a quick one-off JSON baseline (drift_tools.py), or a local SQLite history (drift_baseline/compare/history) that remembers every snapshot so you can compare and trend over time. Works offline on local HTML or by fetching a URL through the shared SSRF guard.

Triggers

• "seo drift" / "baseline" / "deployment check"
• "track changes" / "did anything break" / "seo regression"
• "compare seo" / "before and after" / "monitor seo changes"

Inputs

• A URL (fetched, SSRF-guarded) or local HTML file
• Mode: a one-off JSON baseline+diff, or a stored SQLite baseline / compare / trend
• Optional: a --db path (default <cwd>/.seo-drift/baselines.db under your workspace; it refuses to default inside the plugin — run from your project, or pass --db to a path under your workspace), a --label (e.g. prod, pre-deploy), a --baseline-id

Steps

1. Capture a baseline into the SQLite store (before a deploy, or at handoff):

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/drift_baseline.py" --url <URL> --db .seo-drift/baselines.db --label pre-deploy   # or --file page.html; add --robots robots.txt for rule D15

   Records title, meta description, h1, canonical, meta robots, OG tags, schema-block count, h2 count, and word count (the canonical capture set from drift_tools.py), tagged with a timestamp and label, indexed by URL.
2. Compare after a change against the stored baseline:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/drift_compare.py" --url <URL> --db .seo-drift/baselines.db

   Resolves the latest baseline for that URL (or --label / --baseline-id), captures fresh, and runs the severity engine. It treats adding noindex/nofollow and a canonical flip or drop as critical, title / h1 / schema-loss changes as high, and meta-description / OG / h2 / word-count drift as advisory (word-count moves under 20% are suppressed as editing noise). Full rationale: references/seo-drift/severity-model.md.
3. Trend the history to see drift across deploys:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/drift_history.py" --url <URL> --db .seo-drift/baselines.db --trend

   Lists stored baselines, or with --trend reports the per-transition change count and critical/high/advisory tally — a regression timeline where a deploy that quietly added noindex shows up as a critical-count spike.
4. Quick one-off (no store): for a single before/after without history, use the original JSON path — drift_tools.py --capture --out baseline.json, then drift_tools.py --diff --baseline baseline.json. Same capture set; the JSON baseline is a plain file you can commit.
5. Interpret. Walk the regressions worst-first: intended change or accident? Fix any critical/high immediately. The store design is documented in references/seo-drift/sqlite-schema.md.

Outputs

Filed to: the user's project workspace (the SQLite db and any JSON baselines), never the plugin. The engine never estimates a traffic or ranking-position impact from a diff — that would be a synthesized number.

Error Handling

Every row degrades to a real deliverable — a capture, an honest "no drift," or a clear next step — never an empty failure.

Dependencies

• scripts/seo/drift_tools.py (required) — the canonical SEO-element capturer + the one-off JSON capture/diff path; Python 3.10+, standard library only
• scripts/seo/drift_baseline.py (required) — SQLite baseline store + capture-and-store
• scripts/seo/drift_compare.py (required) — compare a fresh capture vs a stored baseline
• scripts/seo/drift_history.py (required) — list/trend stored baselines
• scripts/seo/drift_severity.py (required) — the change→severity engine (rules derived from the captured-element set)
• references/seo-drift/severity-model.md, references/seo-drift/sqlite-schema.md (severity-model + store-schema knowledge, loaded on demand)
• All standard-library only; URL fetches route through the shared scripts/workflow/net_safety.py SSRF guard

Notes

The SQLite history is the upgrade over a loose JSON file: it remembers every snapshot, so "compare against the last prod capture" and "show me how SEO drifted across the last five deploys" are one command. The severity tiers are derived from exactly which on-page elements we capture — adding a captured element adds a rule, removing one silences it (references/seo-drift/severity-model.md). A critical verdict means "a human must confirm this was intended," not "this is a bug" — a planned migration legitimately flips canonicals; the engine's job is to make sure that flip is never silent.

Related: pairs with design-visual-qa for a complete pre/post-deploy regression net — drift catches SEO, visual-qa catches rendering (one-directional reference; neither depends on the other). Baselines are plain SQLite/JSON you can commit.