On Capy, /ship's PR body edits, comments and new PRs no longer go out through `gh` under the machine owner's GitHub account. Each write runs its checks, saves the exact text to a private file and prints a `HOST_PUBLISH:` line that names the repository (and host, off github.com) it belongs to, so Capy's PR tool sends it to the same place `gh` would have. Nothing changes outside Capy (`GSTACK_CAPY` unset). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> Review-Finding: p1/specialist-batched#1 reader=specialist-batched Review-Finding: p1/specialist-batched#3 reader=specialist-batched Review-Finding: p1/red-team#6 reader=red-team Review-Finding: p1/specialist-batched#1 reader=testing Review-Finding: p1/specialist-batched#2 reader=testing
4.7 KiB
Step 19-C: Capy PR body (What changed, Why, Blast radius, Approvals)
Read only when Step 19 printed CAPY_PR: on. Under Capy a person decides the merge from the PR and
the READY report, through a Captain, so the body shows what changed in pictures, why, and who
approved what. Guide: captain.md beside the Capy gstack skill's SKILL.md.
Order. The plain opening lines come first (at most three), then ## What changed, ## Why and ## Blast radius,
then the standard sections. ## What changed holds the pictures below, then the template's themes, without
repeating the captions. gstack-post folds each into a collapsed section. ## Approvals goes inside the closing
Agent notes section, where gstack-ship-receipt write also puts the receipt. A body posted any other way,
Capy's PR tool included, is folded first: pass the output of
~/.claude/skills/gstack/bin/gstack-post fold --body-file "$PR_BODY_FILE" (it posts nothing, and exit 4
with PLAIN_BODY: lines means rewrite the body file first). Under Capy gstack-post and the receipt
commands never write through gh, which signs in as the owner: each prints HOST_PUBLISH: with the files to
publish through the host's PR tool before the next step, to the repo= it names.
- Pick the evidence: one to three before/after pairs, highest-signal first. The first is the
key image.
- UI change: screenshot the changed screen at the base and on this branch with the browse flow, or your host's browser, at the same size.
- Skill or prompt change:
~/.claude/skills/gstack/bin/gstack-pr-shots --path <template or SKILL.md> --heading "<changed section>" --caption "<what changed and why>". - CLI change: save the output of a command this ship already runs, at the base and on this
branch, to files inside the repository (
.gstack/tmp/before.txt,.gstack/tmp/after.txt), then~/.claude/skills/gstack/bin/gstack-pr-shots --before <file> --after <file> --kind terminal --caption "<…>". Never run a command with side effects just to make a picture. - No visible surface: picture the source section or test output that best shows the change.
gstack-pr-shotsrefuses inputs that match the secret scanner (PR_SHOTS_INPUT_REFUSED). Remove the secret from the capture; never work around the refusal.
- Read
SHOT_PNG:. A path: use it.unavailable (…): screenshot the printedshot.htmlwith your own browser at 880 px wide and use that PNG.failed (…): use the text version only. - Upload. Only for a public repository (
gh repo view --json visibility -q .visibilityprintsPUBLIC). A private repository gets the text version, unless the person approved images for it (record that withgstack-approvals add). Upload each PNG with Capy's PR asset tool (tools.pr.uploadAsset). Embed exactly the URL it returns, with the caption as alt text:(a returned bare video URL stays on its own line). If an upload fails, retry once, and only for a transient error. Otherwise use the text version and writeimage upload failed: <reason>under the caption. Never block publication on an image. - Under every image: a one-line caption saying what changed and why, then the contents of the
printed
text.md(a collapsed text before/after, for readers who cannot see the image and for search). ## Why: two or three sentences. The first states the problem in the person's words (the issue, the failed run, or their request, quoted); the rest say what changes for them. No inventory: BAD "Adds a lint and a CI step." GOOD "'The review loop is too overzealous.' Pass 2 now reads only pass 1's range."## Blast radius: the body template's item, written once, here: what else the change touches and the one fact that makes that safe, with the evidence-ladder rung it reached (file:line read, walked failure path, script ran, repro).## Approvals(inside Agent notes): the output of~/.claude/skills/gstack/bin/gstack-approvals render --plan "<the brief's Plan line>", verbatim. It escapes its cells, and the receipt never reads it as an approval citation. A public repo (or unknown visibility) gets onlyApproved: yes|no (record <id>)andPlan: approved (record r-<id>); never pass--fullfor a PR body. If render refuses with aPLAN_*code, it printed nothing: run the fix it names and render again. OnAPPROVAL_RECORD_UNAVAILABLEkeep its text and say so in the READY report. Never type rows by hand.- READY report: attach the key image's PNG to the report you send (Capy's message attachments) and give its uploaded URL, so the Captain can show it inline.