scripts+docs: R21 Task B — daily upstream-PR nudge runbook (#484)

B2JK-Industry · claude · web-flow · commit e3819a09e7bb · 2026-05-03T11:12:38.000+02:00
Adds scripts/nudge-upstream-prs.sh + companion runbook so SBO3L's 4 open upstream PRs/issues get a daily check-in without manual overhead. Catches new comments within 24h + bumps politely once a PR has gone 7+ days quiet. What's watched ============== ensdomains/ensips#71 (ENSIP-26 spec PR) ensdomains/ensips/72 (ENSIP-26 design-Qs discussion issue) Uniswap/universal-router#477 (per-command policy-guarded swap) KeeperHub/cli#57 (IP-1 envelope protocol) The list is hardcoded near top of the script; new targets append in `repo:kind:number:label` form. What the script does ==================== Per-target: 1. gh api repos/$REPO/{pulls|issues}/$NUMBER for metadata 2. Compute "days since last update" from updated_at 3. Pull comments filtered to last 24h, surface new commenters + first 120 chars of each 4. (--bump mode) if quiet ≥ 7d AND no recent self-bump (cooldown), POST a polite "bumping for visibility" comment Safety rails on --bump: - won't bump closed PRs - won't bump a PR we already-bumped within the last 7d - won't auto-reply to comments (manual response only) - read-mostly: only write op is the 7d-cooldown-gated bump Cron suggestion =============== 0 9 * * * cd /path && ./scripts/nudge-upstream-prs.sh --bump > /tmp/sbo3l-nudge.log 2>&1 Exit codes for orchestration: 0 = new activity in last 24h 1 = no new activity (cron can skip downstream notify) 2 = arg parse error Why this matters ================ Per memory `competitor_intel_2026-05-03.md`: Luca (KH) said "going dark for engineering Qs." Bumping is the right tool when sync feedback isn't available — keeps the discussion thread alive without being pushy. For judges scoring sponsor-relationships: visible engagement hardens the "active community participant" claim vs a fire-and-forget upstream PR. Tested locally: dry run reports correctly across all 4 watched targets. Bash syntax clean (`bash -n`). Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/docs/dev4/upstream-pr-engagement-runbook.md b/docs/dev4/upstream-pr-engagement-runbook.md
@@ -0,0 +1,216 @@
+# Upstream-PR daily engagement runbook
+
+> **Audience:** Daniel.
+> **Outcome:** every open SBO3L upstream PR/issue gets a daily
+> automated check; new comments surface within 24h; quiet PRs get
+> a polite nudge once they cross 7 days.
+> **Cost:** $0. Pure `gh` CLI + cron.
+
+## Why this exists
+
+R19+R20 shipped 4 upstream PRs/issues — silence is the default
+state for community PRs at maintainer organisations like
+ENS/Uniswap/KeeperHub. Without proactive engagement:
+
+1. New comments can sit unread for days, killing momentum.
+2. Long-quiet PRs trend toward "stale → ignored → closed."
+3. Judges scoring sponsor-relationships see a snapshot of the
+   discussion thread; visible activity > silent waiting.
+
+The script + cron close those gaps without adding manual work
+to Daniel's day.
+
+## What's watched
+
+| # | Repo | Number | Kind | Description |
+|---|---|---|---|---|
+| 1 | `ensdomains/ensips` | 71 | PR | ENSIP-26 — Agent Identity Records |
+| 2 | `ensdomains/ensips` | 72 | issue | ENSIP-26 design-Qs discussion (5 specific Qs) |
+| 3 | `Uniswap/universal-router` | 477 | PR | Per-command policy-guarded swap pattern |
+| 4 | `KeeperHub/cli` | 57 | PR | IP-1 envelope protocol proposal |
+
+The list is hardcoded in `scripts/nudge-upstream-prs.sh` near the
+top — `WATCH_TARGETS=(...)`. Add new PRs/issues by appending a
+line in `repo:kind:number:label` form.
+
+## What the script does
+
+```bash
+./scripts/nudge-upstream-prs.sh        # report only (read-only)
+./scripts/nudge-upstream-prs.sh --bump  # report + bump-comment when idle ≥ 7d
+```
+
+Per-target, the script:
+
+1. Queries `gh api repos/$REPO/{pulls|issues}/$NUMBER` for
+   metadata.
+2. Computes "days since last update" from the `updated_at`
+   timestamp.
+3. Pulls comments via `gh api repos/$REPO/issues/$NUMBER/comments`
+   filtered to the last 24h. Surfaces new commenters + first 120
+   chars of each comment.
+4. **In `--bump` mode:** if quiet ≥ 7 days AND we haven't
+   already-bumped within the last 7 days (cooldown check), posts
+   a polite "bumping for visibility" comment.
+
+The bump body is short + non-pushy:
+
+```
+Bumping this for visibility -- happy to address any feedback or iterate
+on the design questions if the maintainers have time. The SBO3L reference
+implementation continues shipping (CI green, adapters publishing) so no
+rush on our end; this is just a nudge in case the thread got buried.
+
+If there is a different forum (Discord, Telegram, weekly call) where this
+kind of proposal gets discussed, happy to redirect.
+```
+
+Tone is "we're shipping, just want to know if there's a better
+channel" — not "review my PR pls." Keeps the maintainer
+relationship friendly even on PRs that ultimately don't merge.
+
+## Cron setup (recommended)
+
+Add to your crontab:
+
+```bash
+# 9am daily, bump-comment if any PR has gone 7+ days quiet
+0 9 * * * cd /path/to/SBO3L-ethglobal-openagents-2026 && \
+  ./scripts/nudge-upstream-prs.sh --bump > /tmp/sbo3l-nudge.log 2>&1
+```
+
+Or, if you prefer manual daily runs:
+
+```bash
+# Add to your shell rc file (.bashrc / .zshrc)
+alias nudge='cd /path/to/SBO3L-ethglobal-openagents-2026 && \
+  ./scripts/nudge-upstream-prs.sh --bump'
+```
+
+Then run `nudge` once a day. Output is one screen, takes ~5 sec.
+
+## Sample output (clean state)
+
+```
+===================================================================
+  SBO3L upstream-PR daily nudge — 2026-05-03T08:51:01Z
+  quiet threshold: 7 days
+  bump mode: report-only
+===================================================================
+
+── ENSIP-26 spec PR (ensdomains/ensips#71, kind=pr) ──────────────
+  state:               open
+  last activity:       2026-05-03T05:51:44Z (0d ago)
+  → no comments in last 24h
+
+── ENSIP-26 design-Qs discussion (ensdomains/ensips#72, kind=issue) ──────────────
+  state:               open
+  last activity:       2026-05-03T07:38:43Z (0d ago)
+  → no comments in last 24h
+
+── Universal Router policy-guarded swap (Uniswap/universal-router#477, kind=pr) ──────────────
+  state:               open
+  last activity:       2026-05-03T06:10:38Z (0d ago)
+  → no comments in last 24h
+
+── KH IP-1 envelope protocol (KeeperHub/cli#57, kind=pr) ──────────────
+  state:               open
+  last activity:       2026-05-03T06:15:09Z (0d ago)
+  → no comments in last 24h
+
+===================================================================
+  done.
+  new activity in last 24h: no
+===================================================================
+```
+
+## Sample output (active state — comments arrived)
+
+```
+── ENSIP-26 spec PR (ensdomains/ensips#71, kind=pr) ──────────────
+  state:               open
+  last activity:       2026-05-04T15:22:11Z (0d ago)
+  → 🆕 2 new comment(s) in last 24h
+  → recent commenters:
+       - dhaiwat: This is great — Q3 (Ed25519 vs polymorphic) is the bigge...
+       - ses.eth: I'd push back on Q1 — namespace prefix avoids the colli...
+```
+
+When this happens: stop, read the comments, decide on a response.
+Don't auto-reply via cron; that's pushy + risks bad-tone replies.
+
+## Sample output (bump fires — 7+ days quiet, --bump enabled)
+
+```
+── KH IP-1 envelope protocol (KeeperHub/cli#57, kind=pr) ──────────────
+  state:               open
+  last activity:       2026-05-10T14:00:00Z (8d ago)
+  → no comments in last 24h
+  → idle 8d ≥ 7d, posting bump comment
+  → ✅ bump comment posted
+```
+
+Post-bump, the cooldown kicks in: subsequent runs won't bump
+again for another 7 days even if the thread stays quiet. Prevents
+turning the bump into spam.
+
+## What `--bump` will NOT do (safety rails)
+
+- ❌ Bump on a PR that already has a bump from B2JK-Industry within the last 7 days.
+- ❌ Bump on a closed PR (state ≠ `open`).
+- ❌ Bump on an unfetchable PR (auth issue, repo deleted, etc.).
+- ❌ Auto-reply to comments.
+- ❌ Force-merge or close anything.
+
+The script is **read-mostly**; the only write op is the periodic
+bump comment, gated behind 3 conditions (open + idle ≥ 7d + no
+recent self-bump).
+
+## Exit codes (for cron orchestration)
+
+- **0** — at least one PR had new activity in last 24h.
+- **1** — no new activity (cron can short-circuit a downstream
+  notify step).
+- **2** — argument parse error.
+- **non-zero from gh api** — auth or rate-limit failure on
+  individual targets; script logs + continues.
+
+## Adding a new PR/issue to watch
+
+Edit the `WATCH_TARGETS` array in
+`scripts/nudge-upstream-prs.sh`:
+
+```bash
+WATCH_TARGETS=(
+    "ensdomains/ensips:pr:71:ENSIP-26 spec PR"
+    "ensdomains/ensips:issue:72:ENSIP-26 design-Qs discussion"
+    "Uniswap/universal-router:pr:477:Universal Router policy-guarded swap"
+    "KeeperHub/cli:pr:57:KH IP-1 envelope protocol"
+    "<owner>/<repo>:pr:<number>:<short label>"   # ← add here
+)
+```
+
+Format: `repo:kind:number:label` separated by colons. Avoid
+colons in the label (use dashes / dots).
+
+## Why this matters (judge-grade impact)
+
+- **Sponsor relationships** — visible engagement on upstream PRs
+  hardens "we're an active community participant" claim. Per
+  competitor intel memory: Luca (KH) said "going dark for
+  engineering Qs" — bumping is the right tool when sync feedback
+  isn't available.
+- **Truthfulness** — every "we proposed X to upstream + we're
+  driving the discussion" claim becomes resolvable: a judge can
+  see the bump-comment timestamps in the upstream thread.
+- **Submission posture** — at submission time, the snapshot of
+  each upstream PR shows recent SBO3L activity (either a real
+  comment-and-respond or a documented bump), which reads as
+  "engaged" rather than "fire-and-forget."
+
+## Related artifacts
+
+- [`docs/proof/ensip-upstream-pr.md`](../proof/ensip-upstream-pr.md) — judge evidence for ENSIP-26
+- [`docs/proof/ensip-followup-issue.md`](../proof/ensip-followup-issue.md) — judge evidence for the design-Qs issue
+- [`docs/proof/uniswap-universal-router-pr.md`](../proof/uniswap-universal-router-pr.md) — UR PR evidence
+- [`docs/proof/kh-protocol-pr.md`](../proof/kh-protocol-pr.md) — KH PR evidence
diff --git a/scripts/nudge-upstream-prs.sh b/scripts/nudge-upstream-prs.sh
@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+#
+# nudge-upstream-prs.sh — daily check on SBO3L's open upstream PRs +
+# discussion issues. Run via cron; outputs a one-screen summary + (if
+# 7+ days idle) appends a polite "bumping for visibility" follow-up
+# comment.
+#
+# What it watches (R21 Task B, 2026-05-03):
+#   - ensdomains/ensips#71  (ENSIP-26 — Agent Identity Records)
+#   - ensdomains/ensips/issues/72  (ENSIP-26 — 5 design Qs discussion)
+#   - Uniswap/universal-router#477 (per-command policy-guarded swap)
+#   - KeeperHub/cli#57 (IP-1 envelope protocol proposal)
+#
+# Why a script (not a manual workflow): all four PRs/issues are
+# open-loop — reviewers may not respond for days. Running this
+# daily catches new comments early + nudges politely once the
+# 7-day quiet threshold trips, without requiring Daniel to remember
+# to check.
+#
+# Usage:
+#   ./scripts/nudge-upstream-prs.sh                 # report only
+#   ./scripts/nudge-upstream-prs.sh --bump          # report + bump-comment if idle ≥ 7d
+#   ./scripts/nudge-upstream-prs.sh --quiet-since=N # override the 7-day threshold to N days
+#
+# Output:
+#   stdout = human-readable per-PR status
+#   exit 0 = at least one PR has new activity since last 24h
+#   exit 1 = no new activity (cron can short-circuit downstream notify if 1)
+#
+# Cron suggestion (Daniel-side):
+#   0 9 * * * /path/to/scripts/nudge-upstream-prs.sh --bump > /tmp/nudge.log 2>&1
+#   (9am daily; bump-comment if any PR has gone 7+ days quiet)
+#
+# Requires:
+#   - gh CLI (authenticated as B2JK-Industry / a maintainer)
+#   - jq
+
+set -euo pipefail
+
+QUIET_DAYS=7
+BUMP=0
+
+for arg in "$@"; do
+    case "$arg" in
+        --bump) BUMP=1 ;;
+        --quiet-since=*) QUIET_DAYS="${arg#*=}" ;;
+        *) echo "unknown arg: $arg" >&2; exit 2 ;;
+    esac
+done
+
+# (repo, kind, number, label) tuples for the 4 watch targets.
+# kind = "pr" or "issue".
+WATCH_TARGETS=(
+    "ensdomains/ensips:pr:71:ENSIP-26 spec PR"
+    "ensdomains/ensips:issue:72:ENSIP-26 design-Qs discussion"
+    "Uniswap/universal-router:pr:477:Universal Router policy-guarded swap"
+    "KeeperHub/cli:pr:57:KH IP-1 envelope protocol"
+)
+
+NEW_ACTIVITY_FOUND=0
+TODAY_UNIX=$(date +%s)
+QUIET_THRESHOLD_UNIX=$((TODAY_UNIX - QUIET_DAYS * 86400))
+RECENT_THRESHOLD_UNIX=$((TODAY_UNIX - 86400))     # last 24h
+
+# Polite follow-up template. Kept short + non-pushy. Built with
+# printf to avoid heredoc-vs-command-substitution quoting traps.
+BUMP_BODY="Bumping this for visibility -- happy to address any feedback or iterate on the design questions if the maintainers have time. The SBO3L reference implementation continues shipping (CI green, adapters publishing) so no rush on our end; this is just a nudge in case the thread got buried.
+
+If there is a different forum (Discord, Telegram, weekly call) where this kind of proposal gets discussed, happy to redirect."
+
+echo "==================================================================="
+echo "  SBO3L upstream-PR daily nudge — $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "  quiet threshold: ${QUIET_DAYS} days"
+echo "  bump mode: $([ $BUMP = 1 ] && echo enabled || echo report-only)"
+echo "==================================================================="
+
+for tuple in "${WATCH_TARGETS[@]}"; do
+    IFS=":" read -r REPO KIND NUMBER LABEL <<<"$tuple"
+    echo
+    echo "── $LABEL ($REPO#$NUMBER, kind=$KIND) ──────────────"
+
+    if [ "$KIND" = "pr" ]; then
+        ENDPOINT="repos/$REPO/pulls/$NUMBER"
+        COMMENTS_ENDPOINT="repos/$REPO/issues/$NUMBER/comments"
+    else
+        ENDPOINT="repos/$REPO/issues/$NUMBER"
+        COMMENTS_ENDPOINT="repos/$REPO/issues/$NUMBER/comments"
+    fi
+
+    META=$(gh api "$ENDPOINT" 2>/dev/null) || {
+        echo "  ERROR: gh api failed for $ENDPOINT — auth or repo access issue"
+        continue
+    }
+
+    STATE=$(echo "$META" | jq -r '.state')
+    UPDATED_AT=$(echo "$META" | jq -r '.updated_at')
+    UPDATED_UNIX=$(date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$UPDATED_AT" +%s 2>/dev/null \
+        || date -u -d "$UPDATED_AT" +%s 2>/dev/null)
+    DAYS_SINCE_UPDATE=$(( (TODAY_UNIX - UPDATED_UNIX) / 86400 ))
+    HAS_REVIEWS=$(echo "$META" | jq -r '.review_comments // 0')
+
+    echo "  state:               $STATE"
+    echo "  last activity:       $UPDATED_AT (${DAYS_SINCE_UPDATE}d ago)"
+
+    if [ "$STATE" != "open" ]; then
+        echo "  → not open, skipping"
+        continue
+    fi
+
+    # New comments in the last 24h?
+    NEW_COMMENT_COUNT=$(gh api "$COMMENTS_ENDPOINT" --paginate \
+        --jq '[.[] | select(.created_at > (now - 86400 | strftime("%Y-%m-%dT%H:%M:%SZ")))] | length' \
+        2>/dev/null || echo "0")
+
+    if [ "$NEW_COMMENT_COUNT" -gt 0 ] 2>/dev/null; then
+        echo "  → 🆕 $NEW_COMMENT_COUNT new comment(s) in last 24h"
+        echo "  → recent commenters:"
+        gh api "$COMMENTS_ENDPOINT" --paginate \
+            --jq '.[] | select(.created_at > (now - 86400 | strftime("%Y-%m-%dT%H:%M:%SZ"))) | "       - \(.user.login): \(.body | .[0:120])"' 2>/dev/null
+        NEW_ACTIVITY_FOUND=1
+    else
+        echo "  → no comments in last 24h"
+    fi
+
+    # Bump if idle ≥ QUIET_DAYS AND --bump flag set.
+    if [ $BUMP = 1 ] && [ "$DAYS_SINCE_UPDATE" -ge "$QUIET_DAYS" ]; then
+        # Avoid bump-spam: only bump if the most recent comment is NOT
+        # already a B2JK-Industry bump within the last QUIET_DAYS.
+        LAST_BUMP_FROM_US=$(gh api "$COMMENTS_ENDPOINT" --paginate \
+            --jq '[.[] | select(.user.login == "B2JK-Industry" and (.body | startswith("Bumping this for visibility")))] | last | .created_at // empty' \
+            2>/dev/null || echo "")
+
+        if [ -n "$LAST_BUMP_FROM_US" ]; then
+            LAST_BUMP_UNIX=$(date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$LAST_BUMP_FROM_US" +%s 2>/dev/null \
+                || date -u -d "$LAST_BUMP_FROM_US" +%s 2>/dev/null)
+            DAYS_SINCE_BUMP=$(( (TODAY_UNIX - LAST_BUMP_UNIX) / 86400 ))
+            if [ "$DAYS_SINCE_BUMP" -lt "$QUIET_DAYS" ]; then
+                echo "  → already bumped ${DAYS_SINCE_BUMP}d ago — skipping (bump cooldown)"
+                continue
+            fi
+        fi
+
+        echo "  → idle ${DAYS_SINCE_UPDATE}d ≥ ${QUIET_DAYS}d, posting bump comment"
+        gh api -X POST "$COMMENTS_ENDPOINT" \
+            -f body="$BUMP_BODY" >/dev/null \
+            && echo "  → ✅ bump comment posted" \
+            || echo "  → ❌ bump comment FAILED (auth or rate limit?)"
+    elif [ $BUMP = 1 ]; then
+        echo "  → idle ${DAYS_SINCE_UPDATE}d < ${QUIET_DAYS}d, no bump needed"
+    fi
+done
+
+echo
+echo "==================================================================="
+echo "  done."
+echo "  new activity in last 24h: $([ $NEW_ACTIVITY_FOUND = 1 ] && echo yes || echo no)"
+echo "==================================================================="
+
+[ $NEW_ACTIVITY_FOUND = 1 ] && exit 0 || exit 1
