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"