From edbacd44f53c0fedbd8564066b74d47a57dcf335 Mon Sep 17 00:00:00 2001
From: Sylpheed port agent <port-agent@localhost>
Date: Thu, 3 Sep 2026 20:53:59 +0000
Subject: [PATCH] port: check-citations now FETCHES before judging -- the false
 red is removed, not documented
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

check-all went red on doc-citations for a citation that was correct: the file had
been pushed by the other agent minutes earlier and this scans LOCAL refs. After a
fetch it passes.

🔴 I HAD ALREADY DIAGNOSED THIS AND ONLY FIXED THE WORDING. The previous commit
added a hint telling the reader to fetch and re-run. That documented the cry-wolf
instead of removing it, and left the suite failing on a correct citation -- which
is precisely what the same file's own header says is worse than no check.

Now it fetches first, read-only and best-effort: no network, no remote or no
credentials just means the scan runs against what is already here, and it says so
in its output rather than pretending the result is authoritative.

Suite state at the time: 23 steps ok, this the only failure, and it was not real.
---
 tools/port/check-citations | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/tools/port/check-citations b/tools/port/check-citations
index 8fd2a9a3..e2863d15 100755
--- a/tools/port/check-citations
+++ b/tools/port/check-citations
@@ -39,6 +39,26 @@ CITE = re.compile(
 PEER_REFS = ("origin/auto/frame-blend-draw-path", "origin/main")
 
 
+def refresh_peer_refs() -> bool:
+    """Fetch before judging, so a stale local ref is not reported as a bad path.
+
+    🔴 THIS WAS A FALSE RED IN `check-all`, TWICE. A citation added minutes after
+    the other agent pushed the file resolves NOWHERE here, because this scans
+    LOCAL refs. The first fix only reworded the failure to suggest fetching --
+    which left the suite going red for a correct citation, i.e. it documented the
+    cry-wolf instead of removing it.
+
+    Read-only and best-effort: no network, no remote, or no credentials just means
+    the scan runs against what is already here, exactly as before.
+    """
+    try:
+        return subprocess.run(
+            ["git", "fetch", "--quiet", "origin"],
+            capture_output=True, timeout=60).returncode == 0
+    except Exception:
+        return False
+
+
 def on_a_ref(path: str) -> str | None:
     """The first ref that carries `path`, or None."""
     for ref in PEER_REFS:
@@ -84,6 +104,9 @@ def main() -> int:
               % (len(nb) == 1, len(ng) == 0 and r == 1, "ok" if ok else "🔴 BROKEN"))
         return 0 if ok else 2
 
+    fetched = refresh_peer_refs()
+    print("peer refs: %s" % ("fetched" if fetched else
+                             "NOT fetched -- offline or no remote; results may be stale"))
     files = sorted(glob.glob("docs/port/*.md"))
     resolves, peer, nowhere = scan(files)
     total = resolves + len(peer) + len(nowhere)