Add cached rule freshness checking against ndcourts.gov (v2.0.0)

Rule staleness checks now fetch effective dates from ndcourts.gov and
compare against bundled dates, with results cached for 90 days. Includes
standalone script for manual/forced checks and updated tests.

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

Author: jet52

README.md

@@ -188,7 +188,7 @@ python app.py
 ## Architecture
 
 - **`core/`** — Shared analysis engine (PDF extraction, mechanical checks, semantic checks, report builder)
-- **`scripts/`** — CLI scripts for the Claude Code skill workflow (`check_brief.py`, `build_report.py`)
+- **`scripts/`** — CLI scripts for the Claude Code skill workflow (`check_brief.py`, `build_report.py`, `check_rule_freshness.py`)
 - **`references/`** — Check definitions, rules summary, and bundled rule text
 - **`web/`** — Flask web interface (upload form, report viewer, JSON API)
 - **`SKILL.md`** — Self-contained Claude Code skill definition (bundles all rules and check definitions inline; works with or without PyMuPDF)
@@ -220,13 +220,20 @@ The full text of the following rules is bundled in `references/rules/`:
 | `rule-3.4.md` | N.D.R.Ct. 3.4 | Privacy Protection for Filings |
 | `rule-11.6.md` | N.D.R.Ct. 11.6 | Medium-Neutral Case Citations |
 
-Rules were last copied from the authoritative source on **2026-02-17**.
+Rules were last verified current against ndcourts.gov on **2026-03-07**.
 
-## TODO
+## Rule Freshness Checking
 
-- [ ] **Rule freshness check**: Add a feature (script or startup check) that compares the bundled rule files against the current versions at ndcourts.gov to detect whether any rules have been amended since the bundled copies were last updated. Candidate URLs:
-  - https://www.ndcourts.gov/legal-resources/rules/ndrappp/28
-  - https://www.ndcourts.gov/legal-resources/rules/ndrappp/29
-  - https://www.ndcourts.gov/legal-resources/rules/ndrappp/32
-  - https://www.ndcourts.gov/legal-resources/rules/ndrappp/34
-  - https://www.ndcourts.gov/legal-resources/rules/ndrct/3-4
+The skill automatically checks whether bundled rules are still current by comparing their effective dates against the live versions on ndcourts.gov. This check runs as part of the normal compliance workflow via `get_version_warnings()` in `core/version_check.py`.
+
+- **Cached**: Results are stored in `~/.cache/jetbriefcheck/rule_staleness.json` and reused for 90 days. No network calls on most runs.
+- **Fail-open**: If ndcourts.gov is unreachable, the check silently succeeds.
+- **Per-rule tracking**: Each rule's effective date is tracked independently. If any rule is amended, a warning is emitted identifying which rule changed and linking to the ndcourts.gov page.
+
+To force a live check (bypassing the cache):
+
+```bash
+python3 scripts/check_rule_freshness.py
+```
+
+When a rule is flagged as stale, update the bundled `.md` file, update `BUNDLED_EFFECTIVE_DATES` in `core/version_check.py`, recompute hashes in `version.json`, and bump `rules_verified`.

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jetbriefcheck
-version: 1.8.0
+version: 2.0.0
 description: >-
   Triggers when a user uploads a legal brief PDF for compliance review against the
   North Dakota Rules of Appellate Procedure. Analyzes the brief and produces a
@@ -52,7 +52,9 @@ Use `$VENV_PYTHON` in all subsequent commands instead of hardcoded `python3`.
 
 The user uploads a PDF via drag-and-drop. Save the uploaded file to a temporary location, then execute the phases below.
 
-### Phase 0: Save the Uploaded PDF
+### Phase 0: Update Check and Save the Uploaded PDF
+
+**Update check:** Run `python3 ~/.claude/skills/jetbriefcheck/check_update.py` silently. If it prints output, include it as a note to the user.
 
 Save the uploaded file to the current working directory, preserving its original filename:
 

TODO.md

@@ -0,0 +1,3 @@
+# TODO
+
+(empty)

build_zip.sh

@@ -16,6 +16,7 @@ cp -r "$REPO_ROOT/scripts"    "$DEST/scripts"
 cp    "$REPO_ROOT/SKILL.md"          "$DEST/SKILL.md"
 cp    "$REPO_ROOT/requirements.txt"  "$DEST/requirements.txt"
 cp    "$REPO_ROOT/version.json"      "$DEST/version.json"
+cp    "$REPO_ROOT/check_update.py"    "$DEST/check_update.py"
 
 # Clean build artifacts
 find "$DEST" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

check_update.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Check for skill/plugin updates against the latest GitHub release.
+
+Shared across jet52 projects: jetmemo-skill, jetredline, jetbriefcheck, jetcite.
+Uses a weekly cache to avoid hitting the GitHub API on every invocation.
+Fails open — never blocks the user's work.
+"""
+
+import json
+import sys
+import time
+import urllib.request
+from pathlib import Path
+
+REPO = "jet52/jetbriefcheck"
+SKILL_NAME = "jetbriefcheck"
+
+GITHUB_API = f"https://api.github.com/repos/{REPO}/releases/latest"
+CACHE_DIR = Path.home() / ".cache" / SKILL_NAME
+CACHE_FILE = CACHE_DIR / "update_check.json"
+CHECK_INTERVAL = 7 * 86400  # 1 week in seconds
+TIMEOUT = 3.0
+
+
+def _read_local_version() -> str | None:
+    """Read the locally installed version from version.json."""
+    version_json = Path(__file__).resolve().parent / "version.json"
+    try:
+        data = json.loads(version_json.read_text())
+        return data.get("version")
+    except Exception:
+        return None
+
+
+def _parse_version(v: str) -> tuple[int, ...]:
+    """Parse a semver string into a comparable tuple."""
+    return tuple(int(x) for x in v.split("."))
+
+
+def _read_cache() -> dict | None:
+    """Read the cached update check result."""
+    try:
+        data = json.loads(CACHE_FILE.read_text())
+        if time.time() - data.get("checked", 0) < CHECK_INTERVAL:
+            return data
+    except Exception:
+        pass
+    return None
+
+
+def _write_cache(remote_version: str) -> None:
+    """Write the update check result to cache."""
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        CACHE_FILE.write_text(json.dumps({
+            "checked": time.time(),
+            "remote_version": remote_version,
+        }))
+    except Exception:
+        pass
+
+
+def _fetch_latest() -> str | None:
+    """Fetch the latest release tag from GitHub."""
+    req = urllib.request.Request(
+        GITHUB_API, headers={"Accept": "application/vnd.github+json"}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
+            data = json.loads(resp.read())
+            return data.get("tag_name", "").lstrip("v")
+    except Exception:
+        return None
+
+
+def check_for_update() -> str | None:
+    """Check for updates. Returns an advisory string if one is available, None otherwise."""
+    local = _read_local_version()
+    if not local:
+        return None
+
+    # Try cache first
+    cache = _read_cache()
+    if cache:
+        remote = cache.get("remote_version")
+    else:
+        remote = _fetch_latest()
+        if remote:
+            _write_cache(remote)
+
+    if not remote:
+        return None
+
+    try:
+        if _parse_version(remote) > _parse_version(local):
+            return (
+                f"{SKILL_NAME} v{local} -> v{remote} available: "
+                f"https://github.com/{REPO}/releases/latest"
+            )
+    except (ValueError, TypeError):
+        pass
+
+    return None
+
+
+def main():
+    msg = check_for_update()
+    if msg:
+        print(msg)
+    else:
+        local = _read_local_version() or "unknown"
+        print(f"{SKILL_NAME} v{local} (up to date)")
+
+
+if __name__ == "__main__":
+    main()

core/version_check.py

@@ -4,20 +4,53 @@
 - Local version info reading
 - Remote version check (lightweight, fail-open)
 - Rule content hash verification
-- Rule staleness warning based on age since last verification
+- Rule staleness check against ndcourts.gov (cached, 90-day refresh)
 """
 
 from __future__ import annotations
 
 import hashlib
 import json
+import re
+import sys
 from datetime import date, datetime
 from pathlib import Path
 from typing import Optional
+from urllib.request import Request, urlopen
 
 PROJECT_DIR = Path(__file__).resolve().parent.parent
 VERSION_FILE = PROJECT_DIR / "version.json"
 RULES_DIR = PROJECT_DIR / "references" / "rules"
+STALENESS_CACHE = Path.home() / ".cache" / "jetbriefcheck" / "rule_staleness.json"
+STALENESS_MAX_AGE_DAYS = 90
+
+# Map rule file stems to ndcourts.gov URLs
+RULE_URLS = {
+    "rule-14": "https://www.ndcourts.gov/legal-resources/rules/ndrappp/14",
+    "rule-21": "https://www.ndcourts.gov/legal-resources/rules/ndrappp/21",
+    "rule-28": "https://www.ndcourts.gov/legal-resources/rules/ndrappp/28",
+    "rule-29": "https://www.ndcourts.gov/legal-resources/rules/ndrappp/29",
+    "rule-30": "https://www.ndcourts.gov/legal-resources/rules/ndrappp/30",
+    "rule-32": "https://www.ndcourts.gov/legal-resources/rules/ndrappp/32",
+    "rule-34": "https://www.ndcourts.gov/legal-resources/rules/ndrappp/34",
+    "rule-3.4": "https://www.ndcourts.gov/legal-resources/rules/ndrct/3-4",
+    "rule-11.6": "https://www.ndcourts.gov/legal-resources/rules/ndrct/11-6",
+}
+
+# Effective dates at the time rules were last bundled (update when rules are refreshed)
+BUNDLED_EFFECTIVE_DATES = {
+    "rule-14": "2020-03-01",
+    "rule-21": "2022-03-01",
+    "rule-28": "2025-06-01",
+    "rule-29": "2022-03-01",
+    "rule-30": "2023-01-25",
+    "rule-32": "2024-04-01",
+    "rule-34": "2025-09-01",
+    "rule-3.4": "2025-03-01",
+    "rule-11.6": "2025-03-01",
+}
+
+EFFECTIVE_DATE_RE = re.compile(r"Effective\s+Date[:\s]+(\d{1,2}/\d{1,2}/\d{4})")
 
 
 def load_local_version() -> dict:
@@ -68,30 +101,98 @@ def check_rule_hashes(local_version: dict) -> list[str]:
     return warnings
 
 
-def check_rule_staleness(local_version: dict) -> Optional[str]:
-    """Check if rules are older than the configured freshness threshold.
+def _load_staleness_cache() -> dict:
+    """Load the cached staleness result. Returns empty dict if missing/corrupt."""
+    try:
+        return json.loads(STALENESS_CACHE.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
 
-    Returns a warning string if stale, None otherwise.
-    """
-    verified_str = local_version.get("rules_verified")
-    if not verified_str:
+
+def _save_staleness_cache(data: dict) -> None:
+    """Write staleness cache, creating parent dirs as needed."""
+    try:
+        STALENESS_CACHE.parent.mkdir(parents=True, exist_ok=True)
+        STALENESS_CACHE.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    except OSError:
+        pass  # fail silently — cache is advisory
+
+
+def _fetch_effective_date(url: str, timeout: float = 10.0) -> Optional[str]:
+    """Fetch a rule page on ndcourts.gov and extract the effective date as YYYY-MM-DD."""
+    try:
+        req = Request(url, headers={"User-Agent": "jetbriefcheck-freshness-check"})
+        with urlopen(req, timeout=timeout) as resp:
+            html = resp.read().decode("utf-8", errors="replace")
+    except Exception:
+        return None
+
+    match = EFFECTIVE_DATE_RE.search(html)
+    if not match:
         return None
 
     try:
-        verified_date = datetime.strptime(verified_str, "%Y-%m-%d").date()
+        dt = datetime.strptime(match.group(1), "%m/%d/%Y")
+        return dt.strftime("%Y-%m-%d")
     except ValueError:
         return None
 
-    max_days = local_version.get("rules_freshness_days", 90)
-    age_days = (date.today() - verified_date).days
 
-    if age_days > max_days:
-        return (
-            f"Bundled rules were last verified {age_days} days ago "
-            f"({verified_str}). Consider checking ndcourts.gov for amendments "
-            f"to Rules 28, 29, 30, 32, 34, and 3.4."
-        )
-    return None
+def _check_rules_live() -> list[str]:
+    """Fetch effective dates from ndcourts.gov and compare against bundled dates.
+
+    Returns a list of warning strings for any stale rules. Saves results to cache.
+    """
+    stale = []
+    live_dates = {}
+
+    for rule, url in RULE_URLS.items():
+        bundled = BUNDLED_EFFECTIVE_DATES.get(rule)
+        if not bundled:
+            continue
+        live = _fetch_effective_date(url)
+        if live:
+            live_dates[rule] = live
+            if live != bundled:
+                stale.append(
+                    f"Rule {rule} may be outdated: bundled effective date "
+                    f"{bundled}, ndcourts.gov shows {live}. "
+                    f"Check {url}"
+                )
+
+    _save_staleness_cache({
+        "last_checked": date.today().isoformat(),
+        "live_dates": live_dates,
+        "stale_rules": [s.split(":")[0].replace("Rule ", "") for s in stale],
+        "warnings": stale,
+    })
+
+    return stale
+
+
+def check_rule_staleness(local_version: dict) -> list[str]:
+    """Check bundled rules against ndcourts.gov effective dates (cached).
+
+    Uses a local cache at ~/.cache/jetbriefcheck/rule_staleness.json.
+    Re-checks live every 90 days. Returns a list of warning strings.
+    """
+    cache = _load_staleness_cache()
+    last_checked_str = cache.get("last_checked")
+
+    if last_checked_str:
+        try:
+            last_checked = datetime.strptime(last_checked_str, "%Y-%m-%d").date()
+            age = (date.today() - last_checked).days
+            if age < STALENESS_MAX_AGE_DAYS:
+                return cache.get("warnings", [])
+        except ValueError:
+            pass
+
+    # Cache is missing, expired, or corrupt — check live (fail-open)
+    try:
+        return _check_rules_live()
+    except Exception:
+        return []
 
 
 def fetch_remote_version(timeout: float = 2.0) -> Optional[dict]:
@@ -162,10 +263,8 @@ def get_version_warnings(check_remote: bool = True, timeout: float = 2.0) -> lis
     # Rule hash integrity check
     warnings.extend(check_rule_hashes(local))
 
-    # Rule staleness check
-    staleness = check_rule_staleness(local)
-    if staleness:
-        warnings.append(staleness)
+    # Rule staleness check (cached, checks ndcourts.gov every 90 days)
+    warnings.extend(check_rule_staleness(local))
 
     # Remote version check (fail-open)
     if check_remote:

deploy_skill.py

@@ -17,7 +17,7 @@
 from pathlib import Path
 
 SKILL_NAME = "jetbriefcheck"
-COPY_ITEMS = ["SKILL.md", "scripts", "references", "core", "requirements.txt", "version.json"]
+COPY_ITEMS = ["SKILL.md", "scripts", "references", "core", "requirements.txt", "version.json", "check_update.py"]
 
 
 def _get_skills_dir() -> Path:

scripts/check_brief.py

@@ -28,6 +28,7 @@
 from core.models import BriefType
 from core.pdf_extract import extract_brief
 from core.version_check import get_version_warnings
+from check_update import check_for_update
 
 
 def main():
@@ -48,7 +49,12 @@ def main():
                         help="Skip remote version check")
     args = parser.parse_args()
 
-    # Version and rule freshness warnings
+    # Update check (cached, weekly)
+    update_msg = check_for_update()
+    if update_msg:
+        print(f"Note: {update_msg}", file=sys.stderr)
+
+    # Rule freshness warnings
     warnings = get_version_warnings(check_remote=not args.skip_version_check)
     for w in warnings:
         print(f"Warning: {w}", file=sys.stderr)