Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 68 additions & 6 deletions scripts/super-board-pr-body.sh
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
# some of them. Rewriting the whole body from memory clobbers the blocks another
# lane wrote since you read it; this script touches only the block you name.
#
# super-board-pr-body.sh --pr <N> --block <name> --expect-head <sha> \
# super-board-pr-body.sh --pr <N> --block <name> --expect-head <sha> [--issue <card>] \
# (--body-file <md> | --append-file <md>) [--repo o/r] [--dry-run]
# super-board-pr-body.sh --skeleton # empty body with every marker, in order (history folded)
# super-board-pr-body.sh --time [--config <cfg.json>] # "Oct 2, 10:02 EDT" in config timezone
Expand All @@ -18,23 +18,37 @@
# --expect-head the PR head you based this edit on. The script refuses (exit 6) when
# the PR head is no longer that commit: the block would describe code
# that is not the code on the PR. Required unless --dry-run.
# --issue the card you are working on. Refused (exit 65) when the PR's branch is
# another card's (`issue-<M>-…`). Running inside a card worktree whose
# branch names another card than the PR's is refused the same way.
# --dry-run prints the new body on stdout, edits nothing.
#
# The card is the `issue-<N>-` prefix of the PR's head branch, read from GitHub, not
# from the caller; a branch without one falls back to --issue. The status block is
# checked against this PR (parallel lanes sharing a /tmp file once wrote another
# card's status onto their own PR, and the approval check then refused the human):
# - a `head \`<sha>\`` that is not this PR's head is refused (exit 65)
# - a `Closes/Fixes/Resolves/Refs #N` naming another card is refused (exit 65)
# - a status line with no `Closes #N`/`Refs #N` gets `· Closes #<card>`
# Other blocks are not checked.
#
# Same content twice is a no-op ("unchanged"), so a retried lane exit is safe.
#
# Exits: 0 ok (stdout: updated | unchanged | the body on --dry-run)
# 6 PR head moved · 64 usage · 66 unreadable file · 70 gh failure
# 6 PR head moved · 64 usage · 65 the content or the card is another PR's
# 66 unreadable file · 70 gh failure
set -uo pipefail

BLOCKS="redcheck status problem solution ac history visual risk"
die() { echo "pr-body: $1" >&2; exit "$2"; }

PR=""; BLOCK=""; HEAD=""; BODY_FILE=""; APPEND_FILE=""; REPO=""; DRY=0; MODE="edit"; CONFIG=""
PR=""; BLOCK=""; HEAD=""; BODY_FILE=""; APPEND_FILE=""; REPO=""; DRY=0; MODE="edit"; CONFIG=""; ISSUE=""
while [ $# -gt 0 ]; do
case "$1" in
--pr) PR="$2"; shift 2 ;;
--block) BLOCK="$2"; shift 2 ;;
--expect-head) HEAD="$2"; shift 2 ;;
--issue) ISSUE="$2"; shift 2 ;;
--body-file) BODY_FILE="$2"; shift 2 ;;
--append-file) APPEND_FILE="$2"; shift 2 ;;
--repo) REPO="$2"; shift 2 ;;
Expand Down Expand Up @@ -73,13 +87,14 @@ SRC="${BODY_FILE:-$APPEND_FILE}"
[ -n "$SRC" ] || die "--body-file or --append-file is required" 64
[ -r "$SRC" ] || die "cannot read $SRC" 66
[ "$DRY" -eq 1 ] || [ -n "$HEAD" ] || die "--expect-head <sha> is required (the PR head your edit is based on)" 64
case "$ISSUE" in 0*|*[!0-9]*) die "--issue must be an issue number (got: $ISSUE)" 64 ;; esac

GITHUB_READ="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/super-board-github-read.py"
# REST, not `gh pr view`/`gh pr edit`: this script runs ~3 times per lane per
# card, and the REST core bucket is separate from the GraphQL one the board
# lives on. GH_REPO fills {owner}/{repo}; unset, gh uses the current checkout.
export GH_REPO="${REPO:-${GH_REPO:-}}"; [ -n "$GH_REPO" ] || unset GH_REPO
META=$(python3 "$GITHUB_READ" --kind body -- api "repos/{owner}/{repo}/pulls/$PR" --jq '{headRefOid: .head.sha, body: (.body // "")}' ) || exit $?
META=$(python3 "$GITHUB_READ" --kind body -- api "repos/{owner}/{repo}/pulls/$PR" --jq '{headRefOid: .head.sha, headRefName: .head.ref, body: (.body // "")}' ) || exit $?
NOW=$(printf '%s' "$META" | jq -r '.headRefOid // empty')
if [ -n "$HEAD" ]; then
# Short or full sha both work: the PR head must start with what you passed.
Expand All @@ -91,8 +106,55 @@ if [ -n "$HEAD" ]; then
esac
fi

OLD_TMP=$(mktemp); NEW_TMP=$(mktemp)
trap 'rm -f "$OLD_TMP" "$NEW_TMP"' EXIT
# ---- which card this PR is for ----------------------------------------------
# Branches are `issue-<N>-<slug>` (run.md); read from GitHub, so a wrong --pr can't borrow a card.
card_of() { printf '%s' "$1" | sed -nE 's/^issue-([0-9]+)-.*/\1/p'; }
BRANCH=$(printf '%s' "$META" | jq -r '.headRefName // empty')
CARD=$(card_of "$BRANCH")
if [ -n "$ISSUE" ] && [ -n "$CARD" ] && [ "$ISSUE" != "$CARD" ]; then
die "PR #$PR is branch $BRANCH, the PR for #$CARD, not #$ISSUE — check --pr" 65
fi
HERE=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
HERE_CARD=$(card_of "$HERE")
if [ -n "$HERE_CARD" ] && [ -n "$CARD" ] && [ "$HERE_CARD" != "$CARD" ]; then
die "you are on $HERE (#$HERE_CARD) but PR #$PR is $BRANCH (#$CARD) — check --pr" 65
fi
CARD="${CARD:-$ISSUE}"

OLD_TMP=$(mktemp); NEW_TMP=$(mktemp); SRC_TMP=$(mktemp)
trap 'rm -f "$OLD_TMP" "$NEW_TMP" "$SRC_TMP"' EXIT

# ---- the status block must describe THIS PR -----------------------------------
if [ "$BLOCK" = status ]; then
python3 - "$SRC" "$NOW" "$CARD" "$PR" > "$SRC_TMP" <<'PY' || exit $?
import re, sys
src, head, card, pr = sys.argv[1:5]
text = open(src, encoding="utf-8").read().strip("\n")
def refuse(why):
sys.stderr.write(f"pr-body: {why} — this status belongs to another PR; rewrite it for PR #{pr}\n")
sys.exit(65)
for sha in re.findall(r"\bhead\s+`([0-9a-f]{7,40})`", text):
if head and not head.startswith(sha):
refuse(f"status names head {sha}, PR #{pr} head is {head}")
refs = re.findall(r"\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?|refs?):?\s+#(\d+)\b", text, re.I)
if card:
other = sorted({n for n in refs if n != card})
if other:
refuse(f"status names #{', #'.join(other)}, PR #{pr} is the PR for #{card}")
if not refs:
# The status line: the first alert line that is not the [!TYPE] marker or a needs-you line.
lines = text.split("\n")
cand = [i for i, l in enumerate(lines) if l.strip()
and not re.match(r"\s*>\s*(\[!\w+\]|needs-you:)", l)]
if cand:
lines[cand[0]] = lines[cand[0]].rstrip() + f" · Closes #{card}"
text = "\n".join(lines)
elif not refs:
sys.stderr.write(f"pr-body: warning: PR #{pr} branch has no issue-<N>- prefix and no --issue; the status names no card\n")
sys.stdout.write(text + "\n")
PY
SRC="$SRC_TMP"
fi
printf '%s' "$META" | jq -r '.body // ""' > "$OLD_TMP"

MODE_FLAG=replace; [ -n "$APPEND_FILE" ] && MODE_FLAG=append
Expand Down
9 changes: 7 additions & 2 deletions skills/super-board/references/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,9 +145,14 @@ There is **exactly one branch per issue** and **exactly one PR per issue**. All

Format: `writing-standard.md` § 2. Title = the commit subject format
(`✨ [feat] chat: stream replies`). The body is marker blocks; each lane rewrites only its own
with `.claude/bin/super-board-pr-body.sh --pr <P> --block <name> --expect-head <sha>
with `.claude/bin/super-board-pr-body.sh --pr <P> --issue <N> --block <name> --expect-head <sha>
(--body-file | --append-file) <md>`. The script refuses (exit 6) when the PR head moved since you
read it — re-read, then redo the edit. Builder opens the PR with every block filled
read it — re-read, then redo the edit. It refuses (exit 65) a PR that is another card's, and a
status block naming another card's `Closes #N` or another PR's head: re-read your own PR and
rewrite the block. A status with no `Closes #N`/`Refs #N` gets `· Closes #<card>` added. Write
block files inside your own worktree's git dir (`"$(git rev-parse --git-dir)/sb-status.md"`: per
worktree, never committed), never a shared `/tmp` name: parallel lanes overwrite each other's
files. Builder opens the PR with every block filled
(`super-board-pr-body.sh --skeleton` prints the empty markers).

| Block | Builder | Tester | Reviewer |
Expand Down
9 changes: 6 additions & 3 deletions skills/super-board/references/writing-standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,10 +112,13 @@ Each block closes with `<!-- /sb:<name> -->`.
| State | Alert | Line |
|---|---|---|
| building, in QA, in review | `> [!NOTE]` | `⏳ In review · round 1 · ✅ 2/3 AC · Closes #790 · head \`3f9c2a1\`` |
| merged | `> [!TIP]` | `✅ Merged · \`9c41e07\`` |
| blocked, red check | `> [!WARNING]` | `🛑 Blocked · needs Eric` |
| merged | `> [!TIP]` | `✅ Merged · \`9c41e07\` · Closes #790` |
| blocked, red check | `> [!WARNING]` | `🛑 Blocked · needs Eric · Closes #790` |

A partial PR writes `Refs #N`, never `Closes #N`. A human-only step can ride inside the
A partial PR writes `Refs #N`, never `Closes #N`. Every status line carries its own card's
`Closes #N` (or `Refs #N`), merged and blocked lines too: the approval check reads the link
there. `super-board-pr-body.sh` adds `· Closes #<card>` when the line has none, and refuses a
line that names another card or another PR's head. A human-only step can ride inside the
alert, one `> needs-you: <command>` line each; the merge gate reads it there or under Risk:

```
Expand Down
67 changes: 64 additions & 3 deletions tests/test-pr-body.sh
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,16 @@ is() { [ "$2" = "$3" ] && ok "$1" || bad "$1" "$2" "$3"; }
has() { case "$2" in *"$3"*) ok "$1" ;; *) bad "$1" "contains: $3" "$2" ;; esac; }
hasnt() { case "$2" in *"$3"*) bad "$1" "no '$3'" "found it" ;; *) ok "$1" ;; esac; }

# gh stub (REST): GET pulls/N serves $WORK/body.md and $HEAD_OID; PATCH pulls/N --input - stores the new body.
# gh stub (REST): GET pulls/N serves $WORK/body.md, $HEAD_OID and branch $HEAD_REF through the
# caller's --jq; PATCH pulls/N --input - stores the new body.
cat > "$WORK/gh" <<'STUB'
#!/usr/bin/env bash
printf '%s\n' "$*" >> "$GH_LOG"
case "$*" in
"api -X PATCH repos/{owner}/{repo}/pulls/"*" --input -") jq -j .body > "$BODY" ;;
"api repos/{owner}/{repo}/pulls/"*)
jq -n --arg h "$HEAD_OID" --rawfile b "$BODY" '{head: {sha: $h}, body: $b}' | jq '{headRefOid: .head.sha, body: (.body // "")}' ;;
Q=.; while [ $# -gt 0 ]; do [ "$1" = --jq ] && Q="$2"; shift; done
jq -n --arg h "$HEAD_OID" --arg r "${HEAD_REF:-}" --rawfile b "$BODY" '{head: {sha: $h, ref: $r}, body: $b}' | jq "$Q" ;;
*) echo "unexpected gh call: $*" >&2; exit 1 ;;
esac
STUB
Expand Down Expand Up @@ -55,7 +57,8 @@ printf '> [!TIP]\n> ✅ Merged · `9c41e07`\n' > "$WORK/status.md"
printf '## Risk\n🟢 **Low** · one constant.\n' > "$WORK/risk.md"
printf '| 🔍 qa | ✅ v1 | Oct 2, 11:55 EDT | runs/issue-7-qa-v1/ |\n' > "$WORK/row.md"

run() { : > "$GH_LOG"; "$SCRIPT" "$@" 2>"$WORK/err"; }
# Runs outside any git checkout, so the caller's own branch never counts as a card worktree.
run() { : > "$GH_LOG"; (cd "$WORK" && "$SCRIPT" "$@" 2>"$WORK/err"); }

echo "── replace one block, keep the rest"
is "replace reports updated" "updated" "$(run --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/status.md")"
Expand Down Expand Up @@ -123,6 +126,64 @@ RC=0; run --pr 7 --block ac --expect-head x >/dev/null || RC=$?; is "content fil
OUT=$(run --pr 7 --block ac --dry-run --body-file "$WORK/risk.md"); has "dry run prints the body" "$OUT" "<!-- sb:ac -->"
hasnt "dry run edits nothing" "$(cat "$GH_LOG")" "PATCH"

echo "── the status block belongs to this PR's card"
# Parallel lanes once shared a /tmp status file: one lane wrote another card's
# `Closes #N` and head onto its own PR, and the approval check refused the human's approval.
export HEAD_REF=issue-7-fix-x
cp "$BODY" "$WORK/before.md"
OTHER='> [!NOTE]\n> ⏳ In review · round 1 · Closes #8 · head `bbbbbbb`\n'
printf "$OTHER" > "$WORK/other.md"
RC=0; run --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/other.md" >/dev/null || RC=$?
is "another card's status exits 65" "65" "$RC"
has "says it belongs to another PR" "$(cat "$WORK/err")" "another PR"
hasnt "no edit for another card's status" "$(cat "$GH_LOG")" "PATCH"
is "body unchanged on refusal" "$(cat "$WORK/before.md")" "$(cat "$BODY")"
printf '> [!NOTE]\n> ⏳ In QA · Closes #8 · head `3f9c2a1`\n' > "$WORK/other.md"
RC=0; run --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/other.md" >/dev/null || RC=$?
is "another card's Closes with the right head exits 65" "65" "$RC"
has "names the other card" "$(cat "$WORK/err")" "#8"
printf '> [!NOTE]\n> ⏳ In QA · Closes #7 · head `bbbbbbb`\n' > "$WORK/other.md"
RC=0; run --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/other.md" >/dev/null || RC=$?
is "another PR's head exits 65" "65" "$RC"
printf '> [!NOTE]\n> ⏳ In review · Closes #7 · head `3f9c2a1`\n' > "$WORK/own.md"
is "own status is written" "updated" "$(run --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/own.md")"
has "own Closes kept once" "$(cat "$BODY")" "⏳ In review · Closes #7 · head"
printf '> [!NOTE]\n> ⏳ In QA · head `3f9c2a1`\n' > "$WORK/own.md"
run --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/own.md" >/dev/null
has "status without Closes gets its card" "$(cat "$BODY")" '⏳ In QA · head `3f9c2a1` · Closes #7'
run --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/status.md" >/dev/null
has "merged line gets its card" "$(cat "$BODY")" '✅ Merged · `9c41e07` · Closes #7'
printf '> [!WARNING]\n> 🛑 Blocked · needs you · head `3f9c2a1`\n> needs-you: `npm run db:migrate:live`\n' > "$WORK/own.md"
run --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/own.md" >/dev/null
has "blocked line gets its card" "$(cat "$BODY")" '🛑 Blocked · needs you · head `3f9c2a1` · Closes #7'
has "needs-you line left as written" "$(cat "$BODY")" '> needs-you: `npm run db:migrate:live`
<!-- /sb:status -->'
printf '> [!NOTE]\n> ⏳ In QA · Refs #7 · head `3f9c2a1`\n' > "$WORK/own.md"
run --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/own.md" >/dev/null
has "partial PR keeps Refs" "$(cat "$BODY")" "⏳ In QA · Refs #7 · head"
hasnt "partial PR gets no Closes" "$(sed -n '/sb:status -->/,/\/sb:status/p' "$BODY")" "Closes"
printf '## Problem\n- Closes #8 is only mentioned in prose\n' > "$WORK/prose.md"
is "other blocks are not checked" "updated" "$(run --pr 7 --block problem --expect-head 3f9c2a1 --body-file "$WORK/prose.md")"

echo "── --issue and the card worktree must match the PR's card"
cp "$BODY" "$WORK/before.md"
RC=0; run --pr 7 --issue 8 --block status --expect-head 3f9c2a1 --body-file "$WORK/own.md" >/dev/null || RC=$?
is "--issue naming another card exits 65" "65" "$RC"
has "says whose PR it is" "$(cat "$WORK/err")" "the PR for #7"
is "body unchanged on a wrong --issue" "$(cat "$WORK/before.md")" "$(cat "$BODY")"
is "--issue naming this card is fine" "unchanged" "$(run --pr 7 --issue 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/own.md")"
git init --quiet "$WORK/wt" && git -C "$WORK/wt" symbolic-ref HEAD refs/heads/issue-8-other
RC=0; (cd "$WORK/wt" && "$SCRIPT" --pr 7 --block status --expect-head 3f9c2a1 --body-file "$WORK/own.md" >/dev/null 2>"$WORK/err") || RC=$?
is "a card worktree on another card exits 65" "65" "$RC"
has "names the worktree branch" "$(cat "$WORK/err")" "issue-8-other"
RC=0; run --pr 7 --issue x8 --block status --expect-head 3f9c2a1 --body-file "$WORK/own.md" >/dev/null || RC=$?
is "--issue is a number" "64" "$RC"
export HEAD_REF=tooling-fix
printf '> [!NOTE]\n> ⏳ In review · head `3f9c2a1`\n' > "$WORK/own.md"
run --pr 7 --issue 9 --block status --expect-head 3f9c2a1 --body-file "$WORK/own.md" >/dev/null
has "a branch without a card takes --issue" "$(cat "$BODY")" '⏳ In review · head `3f9c2a1` · Closes #9'
unset HEAD_REF

echo "── skeleton"
SK=$("$SCRIPT" --skeleton)
for b in status problem solution ac history visual risk; do has "skeleton has $b" "$SK" "<!-- sb:$b -->"; done
Expand Down
2 changes: 1 addition & 1 deletion workflows/super-board-wave.js
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ const lanePrompt = (lane, card) => [
`create your own worktree under .claude/worktrees/, work on the issue branch, post the required PR/issue comments,`,
`move the project card yourself, clean up the worktree on exit. Config: ${input.configPath}.`,
BOARD_IO(),
`Commits, PR title, PR body blocks, comments: .claude/skills/super-board/references/writing-standard.md. Rewrite only your own PR body blocks, with .claude/bin/super-board-pr-body.sh.`,
`Commits, PR title, PR body blocks, comments: .claude/skills/super-board/references/writing-standard.md. Rewrite only your own PR body blocks, with .claude/bin/super-board-pr-body.sh --issue ${card.number}; write the block files inside your own worktree's git dir ($(git rev-parse --git-dir)), never a shared /tmp name.`,
...(lane === 'review' ? REVIEW_MEMORY : []),
...(lane === 'qa' && card.status === 'Ready'
? [`This card is labelled qa: it skips Building. Move it Ready → QA yourself, create the issue branch from the base branch, and test what is already there (run.md → "qa cards").`]
Expand Down