Files
gstack/ship/sections/capy-pr.md
T
Garry Tanandcapy-ai[bot] e95cea8404 On Capy, /ship hands its pull request edits and comments to Capy's PR tool, always naming the right repository (GST-3183) (#4518)
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
2026-11-19 11:30:53 +00:00

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.

  1. 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-shots refuses inputs that match the secret scanner (PR_SHOTS_INPUT_REFUSED). Remove the secret from the capture; never work around the refusal.
  2. Read SHOT_PNG:. A path: use it. unavailable (…): screenshot the printed shot.html with your own browser at 880 px wide and use that PNG. failed (…): use the text version only.
  3. Upload. Only for a public repository (gh repo view --json visibility -q .visibility prints PUBLIC). A private repository gets the text version, unless the person approved images for it (record that with gstack-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: ![<caption>](<url>) (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 write image upload failed: <reason> under the caption. Never block publication on an image.
  4. 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).
  5. ## 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."
  6. ## 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).
  7. ## 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 only Approved: yes|no (record <id>) and Plan: approved (record r-<id>); never pass --full for a PR body. If render refuses with a PLAN_* code, it printed nothing: run the fix it names and render again. On APPROVAL_RECORD_UNAVAILABLE keep its text and say so in the READY report. Never type rows by hand.
  8. 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.