Update instructions - part 2

tests/test_meta_contract_guards.py

@@ -43,6 +43,70 @@ def _read(relative_path: str) -> str:
     return (PROJECT_ROOT / relative_path).read_text(encoding="utf-8")
 
 
+BASELINE_SOURCE = "docs/index.md"
+
+# Docs that legitimately discuss versions other than the current baseline: the roadmap plans
+# future work, and migration/deployment notes describe historical phases by name.
+BASELINE_SCAN_EXCLUSIONS = frozenset(
+    {
+        "docs/roadmap_plan.md",
+        "docs/data_migration.md",
+        "docs/cloudflare_tunnel_access.md",
+        "docs/production-runbook.md",
+        "docs/backup_restore.md",
+    }
+)
+
+_BASELINE_DECLARATION = re.compile(r"Current Baseline:\s*V(\d+\.\d+)")
+_CURRENT_VERSION_CLAIM = re.compile(r"\b(?:current|active)\s+V(\d+\.\d+)", re.IGNORECASE)
+
+
+def _declared_baseline() -> str:
+    """Return the one baseline version the canonical doc set must agree on."""
+    match = _BASELINE_DECLARATION.search(_read(BASELINE_SOURCE))
+    assert match is not None, f"{BASELINE_SOURCE} must declare 'Current Baseline: V<major>.<minor>'"
+    return match.group(1)
+
+
+def _baseline_scanned_docs() -> list[Path]:
+    docs_root = PROJECT_ROOT / "docs"
+    return sorted(
+        path
+        for path in docs_root.rglob("*.md")
+        # docs/reviews/** are dated, non-canonical snapshots and are pinned to the version
+        # that was current when they were written.
+        if "reviews" not in path.relative_to(docs_root).parts
+        and path.relative_to(PROJECT_ROOT).as_posix() not in BASELINE_SCAN_EXCLUSIONS
+    )
+
+
+def test_canonical_docs_declare_one_consistent_baseline():
+    """A stale baseline label makes canonical docs read as drift against current code.
+
+    Every canonical doc that names the current baseline must name the same one, so a version
+    bump cannot leave half the authority set describing a superseded release as current.
+    """
+    baseline = _declared_baseline()
+    violations: dict[str, list[str]] = {}
+
+    for path in _baseline_scanned_docs():
+        relative = path.relative_to(PROJECT_ROOT).as_posix()
+        text = path.read_text(encoding="utf-8")
+        stale = {
+            version
+            for pattern in (_BASELINE_DECLARATION, _CURRENT_VERSION_CLAIM)
+            for version in pattern.findall(text)
+            if version != baseline
+        }
+        if stale:
+            violations[relative] = sorted(stale)
+
+    assert violations == {}, (
+        f"Canonical baseline is V{baseline} (declared in {BASELINE_SOURCE}), "
+        f"but these docs claim another version is current: {violations}"
+    )
+
+
 def test_active_contract_files_are_present():
     """Guard the guard: ensure all expected authority files are scanned."""
     missing = [path for path in ACTIVE_CONTRACT_FILES if not (PROJECT_ROOT / path).exists()]