Initial commit: SEO rule engine, auditor, validator, exceptions, mirror

Versioning ~/seo-tools as critical SEO infrastructure (was home-dir only).
Canonical home of seo_rules.py — ResearchOwl will vendor a copy with a CI diff
guard against this repo. No secrets; Ghost access is via the ghst-en wrapper.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+*.token
+*cache*.json

README.md

@@ -0,0 +1,15 @@
+# seo-tools
+
+SEO rule engine + tooling for the Ghost blogs (EN: theexclusionzone.com).
+
+- `seo_rules.py` — shared rule engine (pure functions, no I/O). Single source of truth
+  for thresholds + checks. Consumed by the auditor, the validator, and (vendored) by
+  ResearchOwl's blog pipeline.
+- `seo_audit.py` — Tool A: site-wide auditor (reads all published posts via `ghst-en`).
+- `seo_validate.py` — Tool C: single-post pre-publish validator (`seo-check` wraps this).
+- `seo_exceptions.py` — documented, consciously-accepted waivers (auditor reporting filter).
+- `seo_mirror.py` — OG/Twitter mirroring helper.
+- `phase2_*.py/json` — one-off batch helpers (kept for provenance).
+
+No secrets live here. Ghost access is via the `ghst-en` wrapper (`~/.local/bin`), which
+fetches a staff token on demand from the pod and never writes it to disk.

phase2_apply.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Phase 2 apply — trim 9 long meta_descriptions, keep og/twitter mirrored.
+
+Reads new descriptions from phase2_desc.json (slug -> new meta_description).
+For each post sets meta_description = og_description = twitter_description to the
+SAME new value via a minimal ghst --from-json patch (+ updated_at for Ghost's
+collision check). Touches nothing else. READ-ONLY against meta_title/body/etc.
+"""
+import json, os, subprocess, sys, tempfile
+from seo_audit import fetch_posts
+
+NEW = json.load(open(os.path.join(os.path.dirname(__file__), "phase2_desc.json")))
+
+def apply_one(post, val):
+    body = {"posts": [{
+        "meta_description": val,
+        "og_description": val,
+        "twitter_description": val,
+        "updated_at": post["updated_at"],
+    }]}
+    fd, jp = tempfile.mkstemp(suffix=".json"); os.close(fd)
+    fd, op = tempfile.mkstemp(suffix=".json"); os.close(fd)
+    try:
+        json.dump(body, open(jp, "w"))
+        cmd = f"ghst-en post update {post['id']} --from-json {jp} --json > {op}"
+        r = subprocess.run(cmd, shell=True, stderr=subprocess.PIPE, text=True)
+        if r.returncode != 0:
+            return r.stderr.strip()
+        return None
+    finally:
+        os.unlink(jp); os.unlink(op)
+
+def main():
+    posts = {p["slug"]: p for p in fetch_posts()}
+    ok, fail = [], []
+    for slug, val in NEW.items():
+        p = posts.get(slug)
+        if not p:
+            fail.append((slug, "slug not found in live posts")); print(f"  FAIL {slug}: not found"); continue
+        err = apply_one(p, val)
+        if err:
+            fail.append((slug, err)); print(f"  FAIL {slug}: {err[:90]}")
+        else:
+            ok.append(slug); print(f"  OK   {slug}  (meta/og/twitter desc = {len(val)} chars)")
+    print(f"\nApplied: {len(ok)} | Failed: {len(fail)}")
+    for s, e in fail:
+        print(f"  FAILED {s}: {e}")
+
+if __name__ == "__main__":
+    main()

phase2_desc.json

@@ -0,0 +1,11 @@
+{
+  "rendlesham-forest-incident-1980": "Military witnesses, physical trace evidence, and official government files — the most thoroughly documented UFO case in British history.",
+  "david-grusch-capitol-2026-whistleblower-uap-disclosure": "Three years after his sworn testimony, Grusch returned to Capitol Hill demanding the declassification Congress still hasn't delivered.",
+  "malmstrom-1967-ufo-nuclear-missiles-incident": "In 1967, UFOs were seen over Malmstrom AFB as twenty nuclear missiles went offline at once. Boeing found no technical explanation.",
+  "spielberg-disclosure-day-2026-uap-film": "Spielberg's \"Disclosure Day\": how fifty years of research turned Hollywood's greatest UFO skeptic into a believer.",
+  "pursue-release-3-cia-confession-apollo-uap-files-2026": "The Pentagon's third UAP release: a CIA confession about spy planes, Apollo lunar anomalies, and 294 files spanning 82 years.",
+  "immaculate-constellation-secret-uap-program-congress": "A 2024 whistleblower document alleges a secret Pentagon UAP program. Nineteen months later, it's still neither confirmed nor denied.",
+  "aaro-ufo-investigation-eight-decades-us-government-research": "AARO found no alien technology after 80 years of investigation. What the Pentagon's UFO office discovered — and what it didn't.",
+  "gimbal-gofast-pentagon-analysis-uap-videos": "Five years after the Pentagon released GIMBAL and GOFAST, both remain unidentified. The data that would resolve them is still secret.",
+  "222-declassified-ufo-files-reveal-hide-unanswered-2026": "222 files, 82 years of records. What the Pentagon's largest UAP declassification reveals, what it hides, and what it leaves unanswered."
+}

seo_audit.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""
+Tool A — site-wide SEO auditor for theexclusionzone.com (EN, Ghost).
+
+READ-ONLY. Fetches every published post via the ghst-en wrapper (Ghost Admin API,
+staff token pulled on-demand from the pod — nothing written to disk), runs the
+shared rule engine (seo_rules.py), and prints:
+  1. a summary of aggregate violations,
+  2. a per-post table sorted worst-first,
+  3. a ranked "fix this first" list.
+
+Usage:
+    python3 seo_audit.py                # fetch live, full report
+    python3 seo_audit.py --json cache.json   # audit a saved posts JSON instead of fetching
+    python3 seo_audit.py --save cache.json   # fetch live AND save the raw JSON
+
+Changes NOTHING in Ghost.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from collections import Counter
+
+import seo_rules as R
+import seo_exceptions as X
+
+
+def partition(post, violations):
+    """Split one post's violations into (actionable, accepted, info).
+
+    'accepted' = an actionable-severity violation whose (rule, slug) is a
+    documented waiver in seo_exceptions — kept OUT of the to-fix count and shown
+    in its own section. The rule still ran; this is a reporting-side filter only.
+    """
+    slug = post.get("slug")
+    actionable, accepted, info = [], [], []
+    for v in violations:
+        if v.severity == R.INFO:
+            info.append(v)
+        elif X.accepted_reason(v.rule, slug):
+            accepted.append(v)
+        else:
+            actionable.append(v)
+    return actionable, accepted, info
+
+
+def fetch_posts():
+    """Pull all published posts (with html) via ghst-en. Returns list[dict].
+
+    We redirect ghst's stdout to a temp file rather than capturing the pipe:
+    ghst's output is ~750 KB and a captured PIPE truncates at the 64 KB pipe
+    buffer, whereas a file redirect gets the whole document.
+    """
+    fd, path = tempfile.mkstemp(suffix=".json", prefix="seo_audit_")
+    os.close(fd)
+    try:
+        cmd = ("ghst-en post list --status published --limit 100 "
+               "--formats html,lexical --json > " + path)
+        r = subprocess.run(cmd, shell=True, stderr=subprocess.PIPE, text=True)
+        if r.returncode != 0:
+            sys.exit(f"ghst-en fetch failed:\n{r.stderr}")
+        data = json.load(open(path))
+        return data["posts"] if isinstance(data, dict) and "posts" in data else data
+    finally:
+        os.unlink(path)
+
+
+def load_posts(path):
+    data = json.load(open(path))
+    return data["posts"] if isinstance(data, dict) and "posts" in data else data
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--json", help="audit a saved posts JSON instead of fetching live")
+    ap.add_argument("--save", help="save fetched raw posts JSON to this path")
+    args = ap.parse_args()
+
+    if args.json:
+        posts = load_posts(args.json)
+        src = f"file {args.json}"
+    else:
+        posts = fetch_posts()
+        src = "live (ghst-en, Ghost Admin API)"
+        if args.save:
+            json.dump({"posts": posts}, open(args.save, "w"), indent=2)
+
+    results = []  # (post, actionable, accepted, info, score)
+    for p in posts:
+        v = R.check_post(p)
+        actionable, accepted, info = partition(p, v)
+        # score ranks worst-first on ACTIONABLE severity only — accepted waivers
+        # and INFO don't push a post up the list.
+        results.append((p, actionable, accepted, info, R.score(actionable)))
+
+    # worst-first: by actionable severity score, then actionable count, then slug
+    results.sort(key=lambda t: (-t[4], -len(t[1]), t[0]["slug"]))
+
+    total_posts = len(posts)
+    # SUMMARY counts reflect ACTIONABLE violations only (waived items excluded).
+    posts_with_rule = Counter()
+    for _, actionable, _, _, _ in results:
+        for rule in {v.rule for v in actionable}:
+            posts_with_rule[rule] += 1
+
+    clean = sum(1 for _, actionable, _, _, _ in results if not actionable)
+    accepted_total = sum(len(acc) for _, _, acc, _, _ in results)
+
+    # ---- header ----
+    print("=" * 78)
+    print(f"  SEO AUDIT — theexclusionzone.com   source: {src}")
+    print(f"  {total_posts} published posts   |   {clean} clean (no actionable issues)"
+          + (f"   |   {accepted_total} accepted exception(s) waived" if accepted_total else ""))
+    print(f"  JSON-LD: handled globally by Edition-main theme — not flagged per post")
+    print("=" * 78)
+
+    # ---- summary ----
+    print("\nSUMMARY — violations by rule (most posts affected first):\n")
+    LABEL = {
+        "meta_description.missing":  "meta_description MISSING",
+        "meta_description.too_long": f"meta_description > {R.META_DESC_MAX}",
+        "meta_title.missing":        "meta_title missing (falls back to title)",
+        "meta_title.too_long":       f"meta_title > {R.META_TITLE_MAX}",
+        "custom_excerpt.too_long":   f"custom_excerpt > {R.CUSTOM_EXCERPT_MAX}",
+        "og_title.empty":            "og_title empty",
+        "og_description.empty":      "og_description empty",
+        "twitter_title.empty":       "twitter_title empty",
+        "twitter_description.empty": "twitter_description empty",
+        "feature_image.missing":     "feature_image missing",
+        "feature_image_alt.missing": "feature_image_alt missing",
+        "internal_links.too_few":    f"internal links < {R.MIN_INTERNAL_LINKS}",
+        "title_eq_meta_title":       "meta_title == title (info)",
+    }
+    # severity per rule (look one up from any occurrence, incl. waived ones)
+    sev_of = {}
+    for _, actionable, accepted, info, _ in results:
+        for v in actionable + accepted + info:
+            sev_of[v.rule] = v.severity
+    for rule, _ in sorted(posts_with_rule.items(),
+                          key=lambda kv: (-sev_of.get(kv[0], 0), -kv[1])):
+        sev = R.SEV_NAME[sev_of.get(rule, 0)]
+        print(f"  [{sev:4}] {posts_with_rule[rule]:2}/{total_posts} posts  "
+              f"{LABEL.get(rule, rule)}")
+
+    # ---- per-post table ----
+    print("\n" + "-" * 78)
+    print("PER-POST (worst first) — score = summed severity (HIGH 3 / MED 2 / LOW 1)\n")
+    print(f"{'score':>5}  {'slug':45} issues")
+    print(f"{'-'*5}  {'-'*45} {'-'*20}")
+    for p, actionable, accepted, info, sc in results:
+        if not actionable:
+            note = "✓ clean" + (f"  ({len(accepted)} accepted exception)" if accepted else "")
+            print(f"{sc:5}  {p['slug'][:45]:45} {note}")
+            continue
+        tags = ", ".join(sorted({v.rule for v in actionable}))
+        print(f"{sc:5}  {p['slug'][:45]:45} {tags}")
+
+    # ---- detail per non-clean post ----
+    print("\n" + "-" * 78)
+    print("DETAIL\n")
+    for p, actionable, accepted, info, sc in results:
+        if not actionable and not info:
+            continue
+        print(f"• {p['slug']}   (score {sc})")
+        for v in sorted(actionable, key=lambda x: -x.severity):
+            print(f"    [{R.SEV_NAME[v.severity]:4}] {v.message}"
+                  + (f"   → {v.fix}" if v.fix else ""))
+        for v in info:
+            print(f"    [INFO] {v.message}")
+        print()
+
+    # ---- accepted exceptions (won't fix — documented) ----
+    if accepted_total:
+        print("-" * 78)
+        print("ACCEPTED EXCEPTIONS (won't fix — documented decisions, NOT in the count)\n")
+        for p, actionable, accepted, info, sc in sorted(results, key=lambda t: t[0]["slug"]):
+            for v in accepted:
+                reason = X.accepted_reason(v.rule, p["slug"])
+                print(f"• {p['slug']}")
+                print(f"    [{R.SEV_NAME[v.severity]:4}] {v.message}")
+                print(f"    waived: {reason}")
+        print()
+
+    # ---- ranked guidance ----
+    print("-" * 78)
+    print("FIX FIRST (by impact / effort):\n")
+    md_missing = posts_with_rule.get("meta_description.missing", 0)
+    md_long = posts_with_rule.get("meta_description.too_long", 0)
+    links = posts_with_rule.get("internal_links.too_few", 0)
+    og = posts_with_rule.get("og_title.empty", 0)
+    alt = posts_with_rule.get("feature_image_alt.missing", 0)
+    rank = []
+    if md_missing:
+        rank.append(f"meta_description MISSING on {md_missing} post(s) — HIGH impact, "
+                    f"controls the Google snippet. Write unique 140–145-char descriptions.")
+    if md_long:
+        rank.append(f"meta_description > {R.META_DESC_MAX} on {md_long} post(s) — trim so the "
+                    f"snippet isn't truncated (real ranking/CTR impact).")
+    if links:
+        rank.append(f"<{R.MIN_INTERNAL_LINKS} internal links on {links} post(s) — add 2–3 contextual "
+                    f"links to related articles (helps crawl + topical authority).")
+    if og:
+        rank.append(f"Empty OG/Twitter fields on {og} post(s) — SAFEST AUTO-FIX: mirror "
+                    f"meta_title/description into og_* and twitter_*. Highest count, lowest risk.")
+    if alt:
+        rank.append(f"Missing feature_image_alt on {alt} post(s) — quick accessibility + image-SEO win.")
+    for i, line in enumerate(rank, 1):
+        print(f"  {i}. {line}")
+    print()
+
+
+if __name__ == "__main__":
+    main()

seo_exceptions.py

@@ -0,0 +1,60 @@
+"""
+Accepted SEO exceptions — consciously-waived findings for SPECIFIC posts.
+
+This is an A-side (auditor) REPORTING filter, NOT a rule change. The shared rule
+engine (seo_rules.py) still CHECKS every rule on every post; the auditor simply
+moves a matching violation into a separate "Accepted exceptions (won't fix —
+documented)" section so the headline "issues to fix" count reflects only
+genuinely-actionable items. Each waiver carries its REASON (no silent skips).
+
+Structure:   EXCEPTIONS[rule_family][slug] = "documented reason"
+
+Scope:
+  - A waiver applies ONLY to the named rule family for the named slug. Any OTHER
+    rule the same post violates still surfaces as a real issue.
+  - A waiver is matched against a Violation whose `rule` equals the family key or
+    starts with "<family>." — so "internal_links" covers "internal_links.too_few".
+  - If a post later stops violating the rule (e.g. a link is added and it clears
+    the threshold), there's simply no violation to waive — the waiver is moot.
+
+Tool C (seo_validate.py, pre-publish validator) deliberately does NOT consult
+this registry: exceptions are per-EXISTING-post decisions; a brand-new draft is
+held to the full standard.
+"""
+
+EXCEPTIONS = {
+    # internal_links < 2 — these posts are intentionally left as-is because there
+    # is no honest 2nd internal-link target in their prose; forcing one would hurt
+    # quality. (Decided 2026-06-23.)
+    "internal_links": {
+        "roswell-1947-ufo-incident":
+            "1 link (Spielberg); no 2nd entity in prose maps to an article — "
+            "forcing a link would hurt quality.",
+        "manises-1979-spain-ufo-incident":
+            "1 link (Canary Islands); no 2nd entity in prose maps to an article.",
+        "betty-barney-hill-1961-abduction":
+            "1 link (alien abduction → travis-walton, thematic); no 2nd honest target.",
+        "malmstrom-1967-ufo-nuclear-missiles-incident":
+            "1 link (Grusch); the only entity named in the prose.",
+        "rendlesham-forest-incident-1980":
+            "0 links; genuinely isolated — no entity in prose maps to one of our articles.",
+        "phoenix-lights-1997":
+            "0 links; only thematic candidates are stretches — left as-is.",
+        "canary-islands-1976-ufo-sighting":
+            "1 link (reciprocal → manises); no honest 2nd entity in prose — "
+            "Spanish case, self-contained.",
+    },
+}
+
+
+def accepted_reason(rule, slug):
+    """Return the documented waiver reason if (rule, slug) is an accepted
+    exception, else None.
+
+    Matches a rule-family key to a Violation whose `rule` is the key itself or
+    "<key>.<detail>" (e.g. family "internal_links" matches "internal_links.too_few").
+    """
+    for family, slugs in EXCEPTIONS.items():
+        if (rule == family or rule.startswith(family + ".")) and slug in slugs:
+            return slugs[slug]
+    return None

seo_mirror.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""
+Tool A — OG/Twitter auto-mirror write path (theexclusionzone.com, Ghost).
+
+For each published post, mirror into EMPTY social fields only:
+    og_title           <- meta_title        (only if og_title empty)
+    twitter_title      <- meta_title        (only if twitter_title empty)
+    og_description     <- meta_description   (only if og_description empty)
+    twitter_description<- meta_description   (only if twitter_description empty)
+
+Never overwrites a non-empty field. Touches ONLY those 4 fields (+ updated_at,
+required by Ghost's optimistic-concurrency check). Idempotent: re-running only
+fills what is still empty.
+
+Modes:
+    python3 seo_mirror.py --list                 # fetch live, show posts needing mirror
+    python3 seo_mirror.py --apply <slug>         # apply to ONE post
+    python3 seo_mirror.py --apply-all [--skip a,b]  # apply to all needing, minus skips
+
+Reuses fetch + emptiness logic from the audit engine. READ-ONLY in --list.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+import seo_rules as R
+from seo_audit import fetch_posts
+
+SOCIAL = {
+    "og_title":            "meta_title",
+    "twitter_title":       "meta_title",
+    "og_description":      "meta_description",
+    "twitter_description": "meta_description",
+}
+
+
+def build_patch(post):
+    """Return {field: source_value} for each EMPTY social field with a non-empty source."""
+    patch = {}
+    for field, src in SOCIAL.items():
+        if R._empty(post.get(field)):
+            srcval = post.get(src)
+            if not R._empty(srcval):
+                patch[field] = srcval
+    return patch
+
+
+def needing(posts):
+    out = []
+    for p in posts:
+        patch = build_patch(p)
+        if patch:
+            out.append((p, patch))
+    return out
+
+
+def apply_one(post, patch):
+    """PATCH one post via ghst-en with a minimal --from-json body. Returns ghst JSON."""
+    body = {"posts": [dict(patch, updated_at=post["updated_at"])]}
+    fd, jpath = tempfile.mkstemp(suffix=".json", prefix="mirror_patch_")
+    os.close(fd)
+    fd, opath = tempfile.mkstemp(suffix=".json", prefix="mirror_out_")
+    os.close(fd)
+    try:
+        json.dump(body, open(jpath, "w"))
+        cmd = f"ghst-en post update {post['id']} --from-json {jpath} --json > {opath}"
+        r = subprocess.run(cmd, shell=True, stderr=subprocess.PIPE, text=True)
+        if r.returncode != 0:
+            return {"_error": r.stderr.strip()}
+        return json.load(open(opath))
+    finally:
+        os.unlink(jpath)
+        os.unlink(opath)
+
+
+def fmt_patch(patch):
+    return ", ".join(f"{k}←{('meta_title' if 'title' in k else 'meta_description')}" for k in patch)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--list", action="store_true")
+    g.add_argument("--apply", metavar="SLUG")
+    g.add_argument("--apply-all", action="store_true")
+    ap.add_argument("--skip", default="", help="comma-separated slugs to skip")
+    args = ap.parse_args()
+
+    posts = fetch_posts()
+    todo = needing(posts)
+    skip = {s.strip() for s in args.skip.split(",") if s.strip()}
+
+    if args.list:
+        print(f"{len(todo)} post(s) need the OG/Twitter mirror "
+              f"(of {len(posts)} published):\n")
+        for p, patch in sorted(todo, key=lambda t: t[0]["slug"]):
+            print(f"  {p['slug'][:50]:50} fills: {', '.join(patch.keys())}")
+        return
+
+    if args.apply:
+        match = [(p, pt) for p, pt in todo if p["slug"] == args.apply]
+        if not match:
+            sys.exit(f"'{args.apply}' not found among posts needing mirror "
+                     f"(maybe already mirrored, or empty meta source).")
+        p, patch = match[0]
+        print(f"Applying to {p['slug']} ({p['id']}): {fmt_patch(patch)}")
+        res = apply_one(p, patch)
+        if "_error" in res:
+            sys.exit(f"FAILED: {res['_error']}")
+        print("  ghst returned OK.")
+        return
+
+    # --apply-all
+    applied, failed = [], []
+    for p, patch in sorted(todo, key=lambda t: t[0]["slug"]):
+        if p["slug"] in skip:
+            print(f"  SKIP {p['slug']}")
+            continue
+        res = apply_one(p, patch)
+        if "_error" in res:
+            failed.append((p["slug"], res["_error"]))
+            print(f"  FAIL {p['slug']}: {res['_error'][:80]}")
+        else:
+            applied.append(p["slug"])
+            print(f"  OK   {p['slug']}  ({', '.join(patch.keys())})")
+    print(f"\nApplied: {len(applied)} | Failed: {len(failed)} | Skipped: {len(skip)}")
+    if failed:
+        for s, e in failed:
+            print(f"  FAILED {s}: {e}")
+
+
+if __name__ == "__main__":
+    main()

seo_rules.py

@@ -0,0 +1,203 @@
+"""
+Reusable SEO rule engine for The Exclusion Zone (EN) — theexclusionzone.com (Ghost).
+
+Pure functions, NO I/O. Feed it a Ghost Admin API post dict (with `html` format
+included) and it returns a list of Violation(rule, severity, message, fix).
+
+Shared by:
+  - seo_audit.py        — Tool A, site-wide auditor (this engine, run over all posts)
+  - (future) seo_validate.py — Tool C, pre-publish validator (same engine, one draft)
+
+Design note: every check is an independent function registered in RULES. To add a
+rule, write a function (post) -> list[Violation] and append it to RULES. The auditor
+and the validator both just call check_post(); they never re-implement a check.
+"""
+import re
+from collections import namedtuple
+
+SITE_HOST = "theexclusionzone.com"
+
+# ---- thresholds (single source of truth, reused by validator) -------------
+META_TITLE_MAX     = 60
+META_DESC_MAX      = 145
+CUSTOM_EXCERPT_MAX = 300
+MIN_INTERNAL_LINKS = 2
+
+# ---- severity weights (used to rank "worst first") ------------------------
+HIGH, MED, LOW, INFO = 3, 2, 1, 0
+SEV_NAME = {HIGH: "HIGH", MED: "MED", LOW: "LOW", INFO: "INFO"}
+
+# The Edition-main theme injects BlogPosting JSON-LD globally in default.hbs
+# ({{#is "post"}} ... <script type="application/ld+json"> @type BlogPosting),
+# plus Ghost's own {{ghost_head}}. So JSON-LD is handled site-wide and is NOT a
+# per-post rule. Flip to False only if that theme block is ever removed.
+THEME_HANDLES_JSONLD = True
+
+Violation = namedtuple("Violation", "rule severity message fix")
+
+
+def _s(v):
+    return v if isinstance(v, str) else ""
+
+
+def _empty(v):
+    return not (isinstance(v, str) and v.strip())
+
+
+# First path segments that are NOT article posts on a Ghost site (tags, authors,
+# pagination, static content, etc.). Keeps root-relative link counting from
+# treating /tag/foo or /content/images/... as an internal article link.
+NON_POST_PREFIXES = {
+    "tag", "tags", "author", "page", "p", "content", "assets",
+    "rss", "ghost", "members", "404", "sitemap",
+}
+
+
+def _internal_slug(href, self_slug):
+    """Return the article slug an href points to if it's an internal POST link,
+    else None. Accepts both absolute (contains SITE_HOST) and root-relative
+    ("/slug/") forms; rejects protocol-relative ("//host"), anchors, mailto,
+    external links, static assets, and known non-post sections."""
+    if SITE_HOST in href:
+        path = re.sub(r"^https?://[^/]+/", "", href)
+    elif href.startswith("/") and not href.startswith("//"):
+        path = href[1:]
+    else:
+        return None
+    slug = path.strip("/").split("/")[0]
+    if not slug or slug == self_slug:
+        return None
+    if slug in NON_POST_PREFIXES or "." in slug:  # section page or static asset
+        return None
+    return slug
+
+
+def internal_links(post):
+    """Distinct internal article slugs linked from the body, excluding self-links.
+
+    Counts BOTH absolute internal links (href containing SITE_HOST) and
+    root-relative links ("/slug/"), so a Ghost-relative link isn't miscounted as
+    "too few". Tool A (auditor) and Tool C (validator) share this, staying in sync.
+    """
+    html = _s(post.get("html"))
+    self_slug = post.get("slug")
+    out = set()
+    for m in re.finditer(r'href="([^"#]+)"', html):
+        slug = _internal_slug(m.group(1), self_slug)
+        if slug:
+            out.add(slug)
+    return out
+
+
+# --- individual rules -------------------------------------------------------
+
+def r_meta_title(p):
+    mt = _s(p.get("meta_title"))
+    title = _s(p.get("title"))
+    if _empty(mt):
+        sev = MED if len(title) > META_TITLE_MAX else LOW
+        return [Violation("meta_title.missing", sev,
+                          f"meta_title missing → falls back to title ({len(title)} chars"
+                          + (f", which is >{META_TITLE_MAX}!" if len(title) > META_TITLE_MAX else "") + ")",
+                          "set meta_title")]
+    if len(mt) > META_TITLE_MAX:
+        return [Violation("meta_title.too_long", MED,
+                          f"meta_title {len(mt)} chars > {META_TITLE_MAX}", "shorten meta_title")]
+    return []
+
+
+def r_meta_description(p):
+    md = _s(p.get("meta_description"))
+    if _empty(md):
+        return [Violation("meta_description.missing", HIGH,
+                          "meta_description MISSING (no SERP snippet control)", "write meta_description")]
+    if len(md) > META_DESC_MAX:
+        return [Violation("meta_description.too_long", MED,
+                          f"meta_description {len(md)} chars > {META_DESC_MAX} (will be truncated in SERP)",
+                          "shorten meta_description")]
+    return []
+
+
+def r_custom_excerpt(p):
+    ce = _s(p.get("custom_excerpt"))
+    if ce and len(ce) > CUSTOM_EXCERPT_MAX:
+        return [Violation("custom_excerpt.too_long", LOW,
+                          f"custom_excerpt {len(ce)} chars > {CUSTOM_EXCERPT_MAX}", "shorten custom_excerpt")]
+    return []
+
+
+def r_social_fields(p):
+    """OG/Twitter empties — the safest auto-fixable category (mirror meta_*)."""
+    out = []
+    fallbacks = {
+        "og_title":          "meta_title",
+        "og_description":    "meta_description",
+        "twitter_title":     "meta_title",
+        "twitter_description": "meta_description",
+    }
+    for field, src in fallbacks.items():
+        if _empty(p.get(field)):
+            out.append(Violation(f"{field}.empty", LOW,
+                                 f"{field} empty", f"mirror from {src}"))
+    return out
+
+
+def r_feature_image(p):
+    out = []
+    if _empty(p.get("feature_image")):
+        out.append(Violation("feature_image.missing", MED,
+                             "feature_image missing (no social/share card image)", "add feature image"))
+    else:
+        if _empty(p.get("feature_image_alt")):
+            out.append(Violation("feature_image_alt.missing", LOW,
+                                 "feature_image_alt missing (a11y + image SEO)", "add feature image alt text"))
+    return out
+
+
+def r_internal_links(p):
+    n = len(internal_links(p))
+    if n < MIN_INTERNAL_LINKS:
+        return [Violation("internal_links.too_few", MED,
+                          f"{n} internal link(s) < {MIN_INTERNAL_LINKS} (weak interlinking)",
+                          "add internal links to related articles")]
+    return []
+
+
+def r_title_equals_meta(p):
+    mt = _s(p.get("meta_title"))
+    title = _s(p.get("title"))
+    if mt and mt == title:
+        return [Violation("title_eq_meta_title", INFO,
+                          "meta_title identical to title (often fine; review)", "")]
+    return []
+
+
+def r_jsonld(p):
+    if THEME_HANDLES_JSONLD:
+        return []
+    return [Violation("jsonld.missing", MED, "no BlogPosting JSON-LD", "add JSON-LD")]
+
+
+RULES = [
+    r_meta_title,
+    r_meta_description,
+    r_custom_excerpt,
+    r_social_fields,
+    r_feature_image,
+    r_internal_links,
+    r_title_equals_meta,
+    r_jsonld,
+]
+
+
+def check_post(post):
+    """Run every rule against one post dict → list[Violation]."""
+    out = []
+    for rule in RULES:
+        out.extend(rule(post))
+    return out
+
+
+def score(violations):
+    """Total severity weight (for ranking posts worst-first); INFO counts 0."""
+    return sum(v.severity for v in violations)

seo_validate.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Tool C — pre-publish SEO validator (theexclusionzone.com, Ghost).
+
+A single-post GATE around the SHARED rule engine in seo_rules.py. It does NOT
+re-implement any rule — it calls check_post(), the exact same engine Tool A
+(seo_audit.py) runs site-wide, so a threshold change in seo_rules.py changes
+both tools at once.
+
+Run it on a draft (or a freshly generated article) BEFORE publishing to catch
+the issues we just cleaned up site-wide: long meta_description, empty OG/Twitter,
+missing alt, too-few internal links.
+
+Modes:
+    python3 seo_validate.py --slug <slug>     # fetch one post (draft OR published) via ghst-en
+    python3 seo_validate.py --id <post_id>     # same, by id
+    python3 seo_validate.py --json <file>      # validate a post object from a JSON file
+                                               #   (raw post dict, or {"posts":[{...}]})
+
+Output: PASS/FAIL per rule group with the specific issue + fix hint.
+Exit code: 0 if clean (no actionable violations), 1 if any — so it can gate a
+publish workflow. READ-ONLY: never writes to Ghost.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+import seo_rules as R
+
+# Display groups, in report order. Each maps to the rule-id prefixes it owns.
+GROUPS = [
+    ("meta_title",        ("meta_title.",)),
+    ("meta_description",  ("meta_description.",)),
+    ("custom_excerpt",    ("custom_excerpt.",)),
+    ("OG / Twitter",      ("og_title.", "og_description.", "twitter_title.", "twitter_description.")),
+    ("feature_image",     ("feature_image.",)),
+    ("feature_image_alt", ("feature_image_alt.",)),
+    ("internal_links",    ("internal_links.",)),
+]
+
+
+def fetch_one(selector, value):
+    """Fetch a single post (draft or published) via ghst-en → post dict.
+
+    selector is 'slug' or 'id'. Redirect to a temp file (a post with html+lexical
+    can approach the 64 KB pipe-buffer limit)."""
+    fd, path = tempfile.mkstemp(suffix=".json", prefix="seo_validate_")
+    os.close(fd)
+    try:
+        flag = "--slug" if selector == "slug" else ""
+        target = value if selector == "slug" else value
+        cmd = (f"ghst-en post get {flag} {target} --formats html,lexical --json > {path}"
+               if selector == "slug"
+               else f"ghst-en post get {target} --formats html,lexical --json > {path}")
+        r = subprocess.run(cmd, shell=True, stderr=subprocess.PIPE, text=True)
+        if r.returncode != 0:
+            sys.exit(f"ghst-en fetch failed for {selector}={value}:\n{r.stderr}")
+        data = json.load(open(path))
+        return _unwrap(data)
+    finally:
+        os.unlink(path)
+
+
+def _unwrap(data):
+    if isinstance(data, dict) and "posts" in data:
+        return data["posts"][0]
+    if isinstance(data, list):
+        return data[0]
+    return data
+
+
+def load_json(path):
+    return _unwrap(json.load(open(path)))
+
+
+def validate(post):
+    """Run the shared engine and print a per-group PASS/FAIL report.
+    Returns the number of actionable (non-INFO) violations."""
+    violations = R.check_post(post)
+    actionable = [v for v in violations if v.severity > R.INFO]
+    info = [v for v in violations if v.severity == R.INFO]
+
+    slug = post.get("slug", "(no slug)")
+    status = post.get("status", "?")
+    title = post.get("title", "")
+    print("=" * 74)
+    print(f"  PRE-PUBLISH SEO CHECK — {slug}   [status: {status}]")
+    print(f"  {title}")
+    print("=" * 74)
+
+    by_prefix = {}
+    for v in violations:
+        for name, prefixes in GROUPS:
+            if any(v.rule.startswith(p) for p in prefixes):
+                by_prefix.setdefault(name, []).append(v)
+                break
+
+    for name, _ in GROUPS:
+        vs = [v for v in by_prefix.get(name, []) if v.severity > R.INFO]
+        if not vs:
+            print(f"  [PASS] {name}")
+        else:
+            for v in sorted(vs, key=lambda x: -x.severity):
+                hint = f"  → {v.fix}" if v.fix else ""
+                print(f"  [FAIL] {name:18} {v.message}{hint}")
+
+    # JSON-LD is handled globally by the Edition-main theme (see seo_rules).
+    print(f"  [PASS] JSON-LD            (BlogPosting injected globally by theme)"
+          if R.THEME_HANDLES_JSONLD else "  [WARN] JSON-LD not theme-handled")
+
+    for v in info:
+        print(f"  [note] {v.message}")
+
+    print("-" * 74)
+    if actionable:
+        print(f"  RESULT: FAIL — {len(actionable)} issue(s) to fix before publishing.")
+    else:
+        print("  RESULT: PASS — no actionable SEO issues. Clear to publish.")
+    print()
+    return len(actionable)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Pre-publish SEO validator (single post).")
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--slug")
+    g.add_argument("--id")
+    g.add_argument("--json", metavar="FILE")
+    args = ap.parse_args()
+
+    if args.json:
+        post = load_json(args.json)
+    elif args.slug:
+        post = fetch_one("slug", args.slug)
+    else:
+        post = fetch_one("id", args.id)
+
+    n = validate(post)
+    sys.exit(1 if n else 0)
+
+
+if __name__ == "__main__":
+    main()