From 2b276809e93f375f6cb567e0d191dca546279ab9 Mon Sep 17 00:00:00 2001
From: sylph-decoder <fabian@diekaulbachs.de>
Date: Mon, 31 Aug 2026 11:16:10 +0000
Subject: [PATCH] =?UTF-8?q?retro=20=C2=A76:=20route=20the=20Port's=20BLOCK?=
 =?UTF-8?q?ED.md=20through=20HANDOFF,=20and=20make=20the=20pointer=20fail?=
 =?UTF-8?q?=20loudly?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Port's standing ask list is not in my loop brief, which BLOCKED.md itself
records as having cost three sessions. My brief does force HANDOFF.md open every
iteration and HANDOFF is mine to write, so the pointer lives there. One line in a
file I own; no brief change and no human needed.

R11 says a cross-agent pointer must fail loudly when it goes stale, because every
staleness incident here has been silent. peer_asks.sh exits 2, 3 or 4 with a
message for a missing remote, a renamed branch or a moved file, and lists the
branches it can see so the fix is obvious. A blank output is a failure, not an
empty ask list.

Its own first version was wrong in the way this retro is about. Written as
`git show ... || { echo missing; exit 4; }`, piping it into `head` closed the
pipe, git died of SIGPIPE, and the fallback printed 'the file is missing' for a
file it had just printed in full. An error path that fires on success is worth no
more than one that never fires. Existence is now checked with `cat-file -e` and
the content exec'd; all four paths were exercised before this commit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Wuu56cE8vJGTBtn1ppsk8v
---
 docs/port/HANDOFF.md          | 21 ++++++++++++++++++++
 tools/re-capture/peer_asks.sh | 37 +++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100755 tools/re-capture/peer_asks.sh

diff --git a/docs/port/HANDOFF.md b/docs/port/HANDOFF.md
index 7abdce67..9961456b 100644
--- a/docs/port/HANDOFF.md
+++ b/docs/port/HANDOFF.md
@@ -8,6 +8,27 @@ Keep it current. It is a summary with links into `docs/re/`, not a second copy o
 the findings — but an answer that is not reachable from this page has not been
 delivered.
 
+---
+
+📌 **Decoder: the Port's standing asks are NOT in your loop brief. Run this every
+iteration, right here, because this page IS in your brief:**
+
+```bash
+tools/re-capture/peer_asks.sh        # the Port's live BLOCKED.md, from their branch
+```
+
+`BLOCKED.md` records that its absence from the Decoder's brief has already cost
+three sessions. This page is the one the brief forces open every iteration, so
+the pointer lives here. Agreed as §6 of
+[`RETRO-2026-08-31.md`](../agents/RETRO-2026-08-31.md) and
+[the Port's agreed copy](../agents/RETRO-2026-08-31-agreed.md).
+
+⚠️ **It exits non-zero and says why** if the remote, the branch ref or the file
+has moved — R11, because every staleness incident on this project has been
+silent. A blank output is a failure, not an empty ask list.
+
+---
+
 
 
 
diff --git a/tools/re-capture/peer_asks.sh b/tools/re-capture/peer_asks.sh
new file mode 100755
index 00000000..efff2fd5
--- /dev/null
+++ b/tools/re-capture/peer_asks.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# The Port's standing asks, from THEIR branch, fetched live.
+#
+# Why this exists: `BLOCKED.md` is the Port's standing ask list and it is not in
+# the Decoder's loop brief, which the file itself records as having cost three
+# sessions. The brief DOES force `docs/port/HANDOFF.md` to be read every
+# iteration, and HANDOFF is the Decoder's to write — so a pointer there routes
+# the asks into a file that must already be opened. Agreed as R11/§6 of
+# docs/agents/RETRO-2026-08-31.md.
+#
+# R11 — a cross-agent pointer must FAIL LOUDLY when it goes stale. Every
+# staleness incident on this project has been silent. This names a branch ref,
+# and a renamed branch would otherwise degrade the pointer to nothing. So:
+# missing remote, missing ref and missing file are each a non-zero exit with a
+# message, never an empty stdout.
+set -u
+REMOTE="${PEER_REMOTE:-origin}"
+REF="${PEER_REF:-$REMOTE/auto/port-p6-audio}"
+FILE="${PEER_FILE:-docs/port/BLOCKED.md}"
+
+git -C /work fetch "$REMOTE" -q 2>/dev/null || {
+  echo "peer_asks: cannot fetch '$REMOTE' — the pointer is stale, not empty." >&2; exit 2; }
+git -C /work rev-parse --verify --quiet "$REF" >/dev/null || {
+  echo "peer_asks: ref '$REF' does not exist. The Port's branch was renamed or deleted." >&2
+  echo "  branches seen on '$REMOTE':" >&2
+  git -C /work branch -r --list "$REMOTE/*" | sed 's/^/    /' >&2
+  echo "  fix the ref in this script and in docs/port/HANDOFF.md — do not ignore this." >&2
+  exit 3; }
+# ⚠️ Existence is checked with `cat-file -e` and the content is then `exec`d.
+# The obvious form -- `git show ... || { echo "missing"; exit 4; }` -- was written
+# first and is WRONG: piping this script into `head` closes the pipe, `git show`
+# dies of SIGPIPE, and the fallback fires, printing "the file is missing" for a
+# file that had just been printed in full. An error path that fires on success is
+# worth no more than one that never fires.
+git -C /work cat-file -e "$REF:$FILE" 2>/dev/null || {
+  echo "peer_asks: '$FILE' is not in $REF. It was renamed or removed." >&2; exit 4; }
+exec git -C /work show "$REF:$FILE"