fix: docs: verify grounded slice for #545 (closes #782)

docs/issue-545-verification.md

@@ -0,0 +1,40 @@
+# Issue #545 Verification — Grounded Slice Already on Main
+
+**Date:** 2025-01-16
+**Refs:** #545, #719, #57028
+**Purpose:** Prevent duplicate reimplementation of the unreachable-horizon grounded slice.
+
+## What is already on main
+
+| Artifact | Path | Status |
+|----------|------|--------|
+| Unreachable horizon report | `docs/UNREACHABLE_HORIZON_1M_MEN.md` | Committed |
+| Horizon computation script | `scripts/unreachable_horizon.py` | Committed |
+| Existing test coverage | `tests/test_unreachable_horizon.py` | Committed |
+
+## Evidence trail
+
+- **PR #719** — introduced the grounded unreachable-horizon slice (script, doc, tests)
+- **Issue comment #57028** — documented the verification steps and confirmed the slice landed on `main`
+
+## Why this issue uses Refs, not Closes
+
+Issue #545 is a *horizon issue* — a compass toward greater sovereignty, not a bugfix with a fully reachable completion state.
+
+The grounded slice already exists on `main`:
+
+1. `scripts/unreachable_horizon.py` computes whether the 1M-men-in-crisis horizon is reachable on the current machine.
+2. `docs/UNREACHABLE_HORIZON_1M_MEN.md` renders the result as a grounded report.
+3. `tests/test_unreachable_horizon.py` keeps the evidence trail durable in-repo.
+
+This PR adds a verification document and a dedicated test so future workers do not rebuild the same report from scratch.
+
+The horizon itself remains open by design.
+
+## Verification commands
+
+```bash
+python3 -m pytest tests/test_issue_545_verification.py tests/test_unreachable_horizon.py -q
+python3 -m py_compile scripts/unreachable_horizon.py
+python3 scripts/unreachable_horizon.py
+```

tests/test_issue_545_verification.py

@@ -0,0 +1,42 @@
+"""Durable evidence trail: grounded unreachable-horizon slice is on main.
+
+Refs #545, #719, #57028.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+EXPECTED_ARTIFACTS = (
+    ROOT / "docs" / "UNREACHABLE_HORIZON_1M_MEN.md",
+    ROOT / "scripts" / "unreachable_horizon.py",
+    ROOT / "tests" / "test_unreachable_horizon.py",
+    ROOT / "docs" / "issue-545-verification.md",
+)
+
+
+def test_all_grounding_artifacts_exist() -> None:
+    """Every artifact that grounds #545 must be present on disk."""
+    missing = [str(p.relative_to(ROOT)) for p in EXPECTED_ARTIFACTS if not p.exists()]
+    assert not missing, f"missing grounding artifacts: {missing}"
+
+
+def test_unreachable_horizon_script_is_syntactically_valid() -> None:
+    """The horizon script must compile without errors."""
+    import py_compile
+
+    script = ROOT / "scripts" / "unreachable_horizon.py"
+    assert script.exists(), "scripts/unreachable_horizon.py is missing"
+    py_compile.compile(str(script), doraise=True)
+
+
+def test_verification_doc_references_prior_evidence() -> None:
+    """The verification doc must cite PR #719 and issue comment #57028."""
+    doc = ROOT / "docs" / "issue-545-verification.md"
+    assert doc.exists(), "docs/issue-545-verification.md is missing"
+    text = doc.read_text(encoding="utf-8")
+    assert "#719" in text, "verification doc must reference PR #719"
+    assert "#57028" in text, "verification doc must reference issue comment #57028"