feat(skills): Add staleness verifier to cloudflare-ops

Catalog the fast-moving facts cloudflare-ops encodes (Wrangler v4.x major
line, the recommended compatibility_date 2026-06-01, the wrangler.jsonc
config convention) in assets/cloudflare-facts.json and guard them against
silent drift with scripts/check-cloudflare-facts.py, following the §7
offline/live split:

- --offline (PR CI): assets/cloudflare-facts.json parses + carries
  schema/as_of; every catalogued fact's prose_token is still named in the
  skill prose (SKILL.md + references + assets/wrangler.jsonc.template, where
  the compatibility_date pin lives); SKILL.md still carries a dated currency
  note. Exit 0 consistent / 10 drift.
- --live (freshness job, never blocks a PR): wrangler still resolves on npm
  and its latest major matches the documented v4.x line. Exit 10 major drift
  (or package gone) / 7 npm unreachable.

SKILL.md gains a "> Ecosystem facts verified as of 2026-07." currency note,
the existing inline "verified 2026-06" date is bumped to 2026-07, and a
staleness-verifier citation block is added; tests/run.sh exercises the
offline contract (frontmatter, citations, exit-code semantics, --json
envelope, and a negative missing-fact case).

--offline: PASS (exit 0, 4 checks).
--live (recorded): wrangler npm latest 4.107.0 (major 4 == documented v4.x) —
no drift, exit 0.

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

skills/cloudflare-ops/SKILL.md

@@ -13,7 +13,9 @@ when_to_use: "Building, configuring, or deploying Cloudflare Workers; writing or
 
 Cloudflare Workers + Wrangler: runtime patterns, bindings, local dev, secrets, deploy, CI/CD, observability.
 
-**Version context (verified 2026-06):** Wrangler **v4.x** · config is **`wrangler.jsonc`** (Cloudflare's recommended format for new projects — some newer features are JSON-config-only; `wrangler.toml` still works and is widespread in older repos) · deploy command is **`wrangler deploy`** (the old **`wrangler publish` is deprecated** — see [gotchas](#common-gotchas)). Workers can now **serve static assets**, which is the current direction for full-stack and static sites over Pages (see [Workers vs Pages](#workers-vs-pages-decision)).
+> Ecosystem facts verified as of 2026-07.
+
+**Version context (verified 2026-07):** Wrangler **v4.x** · config is **`wrangler.jsonc`** (Cloudflare's recommended format for new projects — some newer features are JSON-config-only; `wrangler.toml` still works and is widespread in older repos) · deploy command is **`wrangler deploy`** (the old **`wrangler publish` is deprecated** — see [gotchas](#common-gotchas)). Workers can now **serve static assets**, which is the current direction for full-stack and static sites over Pages (see [Workers vs Pages](#workers-vs-pages-decision)).
 
 ## Reference Files
 
@@ -178,3 +180,20 @@ wrangler tail                    # stream live logs from the deployed Worker
 2. Auth: `wrangler login` (OAuth) for local; **API token** for CI.
 3. Copy [assets/wrangler.jsonc.template](assets/wrangler.jsonc.template), strip the bindings you don't need, fill in IDs.
 4. `wrangler dev` → `wrangler deploy`.
+
+## Staleness verifier
+
+This skill encodes fast-moving facts (Wrangler major line, recommended `compatibility_date`, `wrangler.jsonc` config convention). [`scripts/check-cloudflare-facts.py`](scripts/check-cloudflare-facts.py) guards them against silent drift:
+
+```bash
+# Structural (PR CI, no network): every catalogued fact's prose_token is still
+# named in this skill's prose (incl. the jsonc template), and the currency
+# note still carries a year.
+python scripts/check-cloudflare-facts.py --offline        # exit 0 consistent, 10 drift
+
+# Live (freshness job, never blocks a PR): wrangler still resolves on npm and
+# its latest major matches the documented v4.x line.
+python scripts/check-cloudflare-facts.py --live            # exit 10 major drift, 7 npm unreachable
+```
+
+The canonical fact set lives in [`assets/cloudflare-facts.json`](assets/cloudflare-facts.json); when the Wrangler major, the recommended compatibility_date, or the config convention changes, update it to match or `--offline` fails CI.

skills/cloudflare-ops/assets/cloudflare-facts.json

@@ -0,0 +1,21 @@
+{
+  "_comment": "Canonical fast-moving facts the cloudflare-ops skill encodes: the Wrangler major line, the recommended compatibility_date, and the config filename convention. scripts/check-cloudflare-facts.py asserts each is still stated in the prose + a dated currency note (--offline), and probes npm for Wrangler major drift (--live). Edit deliberately: a change here is a skill-content decision, not housekeeping.",
+  "schema": "claude-mods.cloudflare-ops.facts/v1",
+  "as_of": "2026-07-05",
+  "wrangler": {
+    "documented_major": 4,
+    "prose_token": "v4.x",
+    "live": {"source": "npm", "product": "wrangler", "compare": "major"},
+    "_comment": "Wrangler v4.x is the skill's assumed major line. --live flags drift if npm's latest wrangler dist-tag leaves major 4 (a 5.x would be a breaking-change release warranting a skill review)."
+  },
+  "compatibility_date": {
+    "documented": "2026-06-01",
+    "prose_token": "2026-06-01",
+    "_comment": "The compatibility_date the skill's jsonc skeleton recommends users pin. Offline-only: it is a deliberate runtime pin, not a live registry fact."
+  },
+  "config_format": {
+    "documented": "wrangler.jsonc",
+    "prose_token": "wrangler.jsonc",
+    "_comment": "The recommended config filename for new projects (Cloudflare's direction; some newer features are JSON-config-only). Offline-only."
+  }
+}

skills/cloudflare-ops/scripts/check-cloudflare-facts.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Staleness verifier for cloudflare-ops: the Wrangler major line, the
+recommended compatibility_date, and the config filename convention must stay
+real, stated, and current.
+
+cloudflare-ops assumes Wrangler v4.x, recommends a `wrangler.jsonc` config,
+and pins a specific `compatibility_date` in its skeleton. Those are exactly
+the facts that drift silently (SKILL-RESOURCE-PROTOCOL.md §7): Wrangler ships
+a v5 and the old `wrangler publish`-era advice rots, the prose stops naming
+`wrangler.jsonc`, or the compatibility_date sits stale — and nobody notices
+for months. Two modes:
+
+  --offline (default, safe for PR CI): structural consistency, no network.
+    * assets/cloudflare-facts.json parses and carries the schema + an as_of date
+    * every catalogued fact's prose_token is still named in the skill prose
+      (SKILL.md + references/*.md + assets/wrangler.jsonc.template)
+    * SKILL.md still carries a dated "verified as of <year>" currency note
+  --live (scheduled freshness job, never a PR gate): does Wrangler still
+    resolve on npm, and has its major moved off the documented v4 line?
+
+Usage:   check-cloudflare-facts.py [--offline | --live] [--catalog FILE] [--skill DIR] [--json] [--timeout S]
+Input:   argv flags only (no stdin).
+Output:  stdout = findings (plain rows, or a --json envelope). Data only.
+Stderr:  the verdict line, notices, errors.
+Exit:    0 ok, 2 usage, 3 catalog/skill missing, 4 catalog unparseable,
+         7 npm unreachable (live, advisory — never a real failure),
+         10 drift found (offline: fact no longer named / currency note gone;
+            live: wrangler gone from npm or major drifted off v4)
+
+Examples:
+  check-cloudflare-facts.py --offline                 # PR CI: facts ⇆ prose consistency
+  check-cloudflare-facts.py --live                    # weekly: wrangler still v4 on npm?
+  check-cloudflare-facts.py --offline --json | jq '.data[]'
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+EX_OK = 0
+EX_USAGE = 2
+EX_NOTFOUND = 3
+EX_UNPARSEABLE = 4
+EX_UNAVAILABLE = 7
+EX_DRIFT = 10
+
+SCHEMA = "claude-mods.cloudflare-ops.facts/v1"
+
+HERE = Path(__file__).resolve().parent
+DEFAULT_CATALOG = HERE.parent / "assets" / "cloudflare-facts.json"
+DEFAULT_SKILL = HERE.parent
+
+NPM_REGISTRY = "https://registry.npmjs.org"
+
+CURRENCY_RE = re.compile(r"verified as of\s+(\d{4})", re.IGNORECASE)
+AS_OF_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+class Finding:
+    __slots__ = ("check", "status", "detail")
+
+    def __init__(self, check: str, status: str, detail: str) -> None:
+        self.check = check
+        self.status = status  # ok | drift | unavailable
+        self.detail = detail
+
+    def as_dict(self) -> dict:
+        return {"check": self.check, "status": self.status, "detail": self.detail}
+
+
+def load_catalog(path: Path) -> dict:
+    if not path.is_file():
+        print(f"error: facts catalog not found: {path}", file=sys.stderr)
+        raise SystemExit(EX_NOTFOUND)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict) or data.get("schema") != SCHEMA:
+            raise ValueError(f"schema must be {SCHEMA!r}")
+        if not AS_OF_RE.match(str(data.get("as_of", ""))):
+            raise ValueError(f"as_of must be YYYY-MM-DD, got {data.get('as_of')!r}")
+        for key in ("wrangler", "compatibility_date", "config_format"):
+            if not isinstance(data.get(key), dict) or "prose_token" not in data[key]:
+                raise ValueError(f"fact {key!r} missing prose_token")
+        return data
+    except (json.JSONDecodeError, KeyError, TypeError, ValueError) as exc:
+        print(f"error: could not parse catalog {path}: {exc}", file=sys.stderr)
+        raise SystemExit(EX_UNPARSEABLE)
+
+
+def read_corpus(skill_dir: Path) -> tuple[str, str]:
+    """Returns (skill_md_text, all_prose_text) across SKILL.md + references/*.md
+    + assets/wrangler.jsonc.template (the compatibility_date pin lives there)."""
+    doc = skill_dir / "SKILL.md"
+    if not doc.is_file():
+        print(f"error: SKILL.md not found under {skill_dir}", file=sys.stderr)
+        raise SystemExit(EX_NOTFOUND)
+    skill_md = doc.read_text(encoding="utf-8", errors="replace")
+    parts = [skill_md]
+    ref_dir = skill_dir / "references"
+    if ref_dir.is_dir():
+        for ref in sorted(ref_dir.glob("*.md")):
+            parts.append(ref.read_text(encoding="utf-8", errors="replace"))
+    template = skill_dir / "assets" / "wrangler.jsonc.template"
+    if template.is_file():
+        parts.append(template.read_text(encoding="utf-8", errors="replace"))
+    return skill_md, "\n".join(parts)
+
+
+def check_offline(catalog: dict, skill_dir: Path) -> list[Finding]:
+    skill_md, corpus = read_corpus(skill_dir)
+    lower = corpus.lower()
+    findings: list[Finding] = []
+
+    if CURRENCY_RE.search(skill_md):
+        m = CURRENCY_RE.search(skill_md)
+        findings.append(Finding("currency-note", "ok", f"currency note dated {m.group(1)}"))
+    else:
+        findings.append(Finding("currency-note", "drift",
+                                "no dated 'verified as of <year>' currency note in SKILL.md"))
+
+    for key in ("wrangler", "compatibility_date", "config_format"):
+        fact = catalog[key]
+        token = str(fact["prose_token"])
+        if token.lower() in lower:
+            findings.append(Finding(f"fact:{key}", "ok", f"{token!r} named in skill prose"))
+        else:
+            findings.append(Finding(f"fact:{key}", "drift",
+                                    f"prose_token {token!r} no longer named in skill prose"))
+    return findings
+
+
+def _npm_latest(pkg: str, timeout: float) -> tuple[str, str]:
+    """Return (status, version-or-detail). status in ok|notfound|unavailable."""
+    url = f"{NPM_REGISTRY}/{urllib.parse.quote(pkg, safe='')}/latest"
+    req = urllib.request.Request(url, headers={"User-Agent": "claude-mods-cloudflare-ops-check/1",
+                                               "Accept": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            payload = resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        if exc.code in (404, 410):
+            return "notfound", str(exc.code)
+        return "unavailable", str(exc.code)
+    except (urllib.error.URLError, TimeoutError, OSError):
+        return "unavailable", ""
+    try:
+        return "ok", json.loads(payload).get("version", "")
+    except json.JSONDecodeError:
+        return "unavailable", "bad-json"
+
+
+def check_live(catalog: dict, timeout: float) -> list[Finding]:
+    findings: list[Finding] = []
+    wr = catalog["wrangler"]
+    documented_major = str(wr["documented_major"])
+    status, ver = _npm_latest(wr["live"]["product"], timeout)
+    if status == "notfound":
+        findings.append(Finding("npm:wrangler", "drift",
+                                "wrangler gone from npm — renamed/removed, review skill"))
+        return findings
+    if status != "ok":
+        findings.append(Finding("npm:wrangler", "unavailable", "npm registry unreachable"))
+        return findings
+    m = re.match(r"\s*(\d+)", ver)
+    latest_major = m.group(1) if m else ""
+    if latest_major and latest_major != documented_major:
+        findings.append(Finding("npm:wrangler", "drift",
+                                f"wrangler@{ver} major {latest_major} != documented v{documented_major}.x — review skill"))
+    else:
+        findings.append(Finding("npm:wrangler", "ok", f"latest {ver} (major {latest_major})"))
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(
+        prog="check-cloudflare-facts.py",
+        description="Verify cloudflare-ops' Wrangler major + config facts stay stated (offline) and current (live).",
+    )
+    mode = p.add_mutually_exclusive_group()
+    mode.add_argument("--offline", action="store_true", help="structural consistency, no network (default)")
+    mode.add_argument("--live", action="store_true", help="probe npm for wrangler major drift")
+    p.add_argument("--catalog", default=str(DEFAULT_CATALOG), help="facts catalog JSON")
+    p.add_argument("--skill", default=str(DEFAULT_SKILL), help="skill directory (SKILL.md + references/ + assets/)")
+    p.add_argument("--timeout", type=float, default=10.0, help="per-request timeout seconds (live)")
+    p.add_argument("--json", action="store_true", help="emit a JSON envelope")
+    p.add_argument("-q", "--quiet", action="store_true", help="suppress stderr progress/summary")
+    try:
+        args = p.parse_args(argv)
+    except SystemExit as exc:
+        return EX_USAGE if exc.code not in (0, None) else (exc.code or EX_OK)
+
+    catalog = load_catalog(Path(args.catalog))
+    live = args.live and not args.offline
+    mode_name = "live" if live else "offline"
+    findings = check_live(catalog, args.timeout) if live else check_offline(catalog, Path(args.skill))
+
+    n_drift = sum(1 for f in findings if f.status == "drift")
+    n_unavail = sum(1 for f in findings if f.status == "unavailable")
+
+    if args.json:
+        print(json.dumps({
+            "data": [f.as_dict() for f in findings],
+            "meta": {"mode": mode_name, "count": len(findings),
+                     "drift": n_drift, "unavailable": n_unavail, "schema": SCHEMA},
+        }, indent=2))
+    else:
+        for f in findings:
+            print(f"{f.check}\t{f.status}\t{f.detail}")
+
+    for f in findings:
+        if f.status != "ok":
+            print(f"  [{f.status.upper()}] {f.check}: {f.detail}", file=sys.stderr)
+    if not args.quiet:
+        print(f"-- {len(findings)} checks: {n_drift} drift, {n_unavail} unavailable", file=sys.stderr)
+
+    if n_drift:
+        return EX_DRIFT
+    if n_unavail:
+        return EX_UNAVAILABLE
+    return EX_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

skills/cloudflare-ops/tests/run.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# Offline self-test for the cloudflare-ops skill — structure, frontmatter, and
+# the staleness-verifier contract (SKILL-RESOURCE-PROTOCOL §7, §10).
+#
+# Usage:   tests/run.sh
+# Input:   none (self-contained; no network, no wrangler install required)
+# Output:  TAP-ish progress on stderr; final PASS/FAIL line.
+# Exit:    0 all pass (or skipped on unsupported platform), 1 any failure.
+#
+# Examples:
+#   tests/run.sh
+#   bash skills/cloudflare-ops/tests/run.sh
+set -uo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+fail=0
+pass=0
+note() { printf '  %s %s\n' "$1" "$2" >&2; }
+ok()   { pass=$((pass+1)); note "ok  " "$1"; }
+bad()  { fail=$((fail+1)); note "FAIL" "$1"; }
+
+# Resolve a *working* python (python3, else python). The bare `command -v` is not
+# enough on Windows, where `python3` is a Microsoft Store stub that exits nonzero.
+PY=""
+for cand in python3 python; do
+  if command -v "$cand" >/dev/null 2>&1 && "$cand" --version >/dev/null 2>&1; then
+    PY="$cand"; break
+  fi
+done
+if [ -z "$PY" ]; then
+  echo "SKIP: no working python interpreter on this platform" >&2
+  exit 0
+fi
+
+# 1. Required directories exist
+for d in scripts references assets tests; do
+  [ -d "$here/$d" ] && ok "dir $d/ exists" || bad "missing dir $d/"
+done
+
+# 2. SKILL.md frontmatter house rules
+skill="$here/SKILL.md"
+if [ -f "$skill" ]; then
+  ok "SKILL.md present"
+  grep -q '^name: cloudflare-ops$' "$skill" && ok "name matches directory" || bad "name != cloudflare-ops"
+  grep -q '^license: MIT$' "$skill" && ok "license: MIT" || bad "missing license: MIT"
+  grep -q '^  author: claude-mods$' "$skill" && ok "metadata.author" || bad "missing metadata.author"
+else
+  bad "SKILL.md missing"
+fi
+
+# 3. Every reference on disk is cited from SKILL.md (no dead weight)
+for ref in "$here"/references/*.md; do
+  base="references/$(basename "$ref")"
+  grep -qF "$base" "$skill" && ok "cited: $base" || bad "uncited reference: $base"
+done
+
+# 4. Every SKILL.md-cited bundled resource exists on disk
+for res in assets/cloudflare-facts.json assets/wrangler.jsonc.template scripts/check-cloudflare-facts.py; do
+  [ -f "$here/$res" ] && ok "resource present: $res" || bad "missing resource: $res"
+done
+
+# 5. check-cloudflare-facts.py — staleness verifier contract (§7, §10), offline-safe
+verifier="$here/scripts/check-cloudflare-facts.py"
+catalog="$here/assets/cloudflare-facts.json"
+ec() { local want="$1" lbl="$2"; shift 2; "$@" >/dev/null 2>&1; local got=$?
+       [ "$got" = "$want" ] && ok "$lbl (exit $got)" || bad "$lbl (want $want got $got)"; }
+if [ -f "$verifier" ]; then
+  "$PY" -m py_compile "$verifier" && ok "verifier: py_compile clean" || bad "verifier: py_compile failed"
+  grep -qE '^Examples:$' "$verifier" && ok "verifier: has Examples block" || bad "verifier: no Examples block (docstring)"
+  "$PY" "$verifier" --help >/dev/null 2>&1 && ok "verifier: --help exits 0" || bad "verifier: --help nonzero"
+  # Offline mode must pass on the skill's own content (internal consistency).
+  ec 0 "verifier: --offline consistent"  "$PY" "$verifier" --offline
+  # Bad flag → USAGE (exit 2); conflicting modes → USAGE.
+  ec 2 "verifier: bad flag → exit 2"     "$PY" "$verifier" --bogus
+  ec 2 "verifier: --offline --live → 2"  "$PY" "$verifier" --offline --live
+  # stdout is data-only: --offline --json must emit parseable JSON.
+  "$PY" "$verifier" --offline --json -q 2>/dev/null \
+    | "$PY" -c 'import json,sys; d=json.load(sys.stdin); assert d["meta"]["schema"]=="claude-mods.cloudflare-ops.facts/v1"' \
+    && ok "verifier: --json envelope parses (stdout clean)" || bad "verifier: --json envelope broken"
+  # Error paths: missing catalog → 3, malformed catalog → 4, drift catalog → 10.
+  TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+  ec 3 "verifier: missing catalog -> 3"  "$PY" "$verifier" --offline --catalog "$TMP/nope.json"
+  printf '{"packages":"x"}' > "$TMP/bad.json"
+  ec 4 "verifier: malformed catalog -> 4" "$PY" "$verifier" --offline --catalog "$TMP/bad.json"
+  # Minimal drift catalog (argv path so MSYS translates it): a fact whose
+  # prose_token is not in the real skill prose -> drift -> exit 10.
+  printf '%s\n' '{"schema":"claude-mods.cloudflare-ops.facts/v1","as_of":"2026-07-05","wrangler":{"documented_major":4,"prose_token":"v9.x","live":{"source":"npm","product":"wrangler","compare":"major"}},"compatibility_date":{"documented":"2030-01-01","prose_token":"2030-01-01"},"config_format":{"documented":"wrangler.jsonc","prose_token":"wrangler.jsonc"}}' > "$TMP/drift.json"
+  ec 10 "verifier: missing fact -> 10" "$PY" "$verifier" --offline --catalog "$TMP/drift.json"
+  # cited from SKILL.md
+  grep -qF "scripts/check-cloudflare-facts.py" "$skill" && ok "verifier: cited from SKILL.md" || bad "verifier: uncited"
+else
+  bad "check-cloudflare-facts.py missing"
+fi
+
+# 6. cloudflare-facts.json — parses, carries schema + the catalogued facts
+"$PY" -c "
+import json, sys
+d = json.load(open(sys.argv[1], encoding='utf-8'))
+assert d['schema'] == 'claude-mods.cloudflare-ops.facts/v1'
+assert d['wrangler']['documented_major'] == 4
+assert d['compatibility_date']['documented']
+assert d['config_format']['documented'] == 'wrangler.jsonc'
+" "$catalog" && ok "cloudflare-facts.json schema + facts" || bad "cloudflare-facts.json invalid"
+
+# 7. Currency note present near the top of the body
+grep -qE 'verified as of [0-9]{4}' "$skill" && ok "currency note present" || bad "no dated currency note"
+
+echo "cloudflare-ops self-test: $pass passed, $fail failed" >&2
+[ "$fail" -eq 0 ]