mdsmithaustin · Oct 24, 2026 · Oct 24, 2026 · Oct 24, 2026 · Oct 24, 2026 · Oct 24, 2026
diff --git a/PORTING.md b/PORTING.md
@@ -46,7 +46,7 @@ Upstream is the source of truth for the workflows themselves. This file records
 - `worktree-audit.sh` and the [Worktree cleanup playbook](skills/poteto-mode/playbooks/worktree-cleanup.md) guard kept files, a port fix for #167 from 2026-10 that can be offered upstream. Steps 4 and 5 own the output contract and removal guard. On sync, preserve the script's NUL-delimited status parsing and explicit `--ignored=matching`, `--untracked-files=normal`, and `--ignore-submodules=none` flags. Preserve the nested `.git` scan, which reports a checkout even under an ignored build cache and skips one under an already reported kept directory. Preserve the `git ls-files -v` count of present skip-worktree and assume-unchanged files as `wip`, the case-insensitive fixed-string `rg -F -i` transcript match, and the `unreadable` result with bucket `hold-kept` when status, `ls-files`, or the scan fails. Preserve the porcelain worktree-path parsing with `sed -n 's/^worktree //p'` for paths with spaces. Keep the regression coverage in `tools/test_worktree_audit.py` and `WorktreeAuditPromises` in `evals/promises/test_scripts.py` when upstream rewrites either file, and keep the `ripgrep` install in the `lint.yml` skills job, without which most of `tools/test_worktree_audit.py` skips. Do not restore upstream's disposable `scratch:N` classification.
 
 - **documentation-impact** (`skills/documentation-impact/`) is a port addition for authoring and independently reviewing documentation affected by a change. Preserve its auto-invocable metadata, `tools/skill-trigger-cases.json` entry, README and guide entries, central Poteto completion trigger, and Babysit and Shipping readiness hooks during sync. Preserve its canonical author result rules. The pass covers local work without a PR and binds any required independent review verdict to the examined artifact and documentation context. Visual tools remain optional. Keep model selection and lifecycle orchestration in the calling workflow.
-- **pr-recap** (`skills/pr-recap/`) is a port addition that posts one reviewer recap comment per pull request: a two-sentence story, one hand-drawn sketch rendered by the bundled Bun tool in `scripts/sketch` and attached with `gh`, a "Not covered" line, and a collapsed details block. `skills/pr-recap/CREDITS.md` carries the MIT notices for the six skills its rules adapt and the OFL notice for the vendored Excalifont subset. On sync, keep the skill, its trigger row, the **Recap** paragraph in Opening a PR, the sketch tests in `tests/skills/pr-recap/`, and their `lint.yml`, `tools/gate-check.sh`, and Dependabot entries.
+- **pr-recap** (`skills/pr-recap/`) is a port addition that posts one reviewer recap comment per pull request: a two-sentence story, one hand-drawn sketch rendered by the bundled Bun tool in `scripts/sketch` and attached with `gh`, a "Not covered" line, and a collapsed details block. `skills/pr-recap/CREDITS.md` carries the MIT notices for the six skills its rules adapt and the OFL notice for the vendored Excalifont subset. On sync, keep the skill, its trigger row, the **Recap** paragraph in Opening a PR, the sketch tests in `tests/skills/pr-recap/`, and their `lint.yml`, `tools/gate-check.sh`, and Dependabot entries. Its refresh trigger in `skills/poteto-mode/references/task-triggers.md` is also a port addition, so keep that line when a sync rewrites the trigger list.
 - **statechart** (`skills/statechart/`) keeps upstream's scripts. Its tests live in `tests/skills/statechart/scripts/test/`, per the tests-out-of-`skills/` rule. Upstream runs them in a `validate-plugins.yml` step. Here they run in the `statechart script tests` step of the `lint.yml` skills job and in the `statechart node tests` line of the `gate-check.sh` test tier, both as `node --test` over `*.test.mjs`. CI uses the runner's preinstalled Node, because `tools/test_repository_hardening.py` bans `setup-node`. On sync, carry upstream changes to that step into both places.
 - **deslop** (`skills/deslop/`) is a port addition that replaces cursor-team-kit's `/deslop` with a pstack-owned code cleanup pass: nineteen numbered rules over the branch's changed hunks, a test run that proves behavior unchanged, and a report. `skills/deslop/CREDITS.md` ships inside the skill directory so the MIT notices travel with every `npx skills` copy. On sync, keep the skill, its trigger row in `tools/skill-trigger-cases.json`, the README and guide entries, poteto-mode's Before every commit or amend trigger, the deslop lines in Opening a PR, both autopilot playbooks, and the multi-phase checklist, step 5's hand-off to the no-comments skill and its Report line, and the ledger promises `deslop-available-for-code`, `opening-a-pr-deslops-diff`, `deslop-cleans-code-slop`, and `deslop-hands-unsettled-comments-to-no-comments`. Upstream never writes `skills/deslop/`; if it ever does, keep whichever version has the rule table.
 - **Gated publish** (port addition, 2026-10). In a repository that gates pushes through no-mistakes, Opening a PR's **Gated publish** section routes every publish, PR creation, restack, and retarget through the no-mistakes CLI, sends work-in-progress snapshots to `refs/pstack/wip/<branch>` or the repository's own agent ref convention, and hands sandbox work to the host. On sync, keep that section, the gated pointers in Babysit, Shipping, Autopilot-full, Autopilot-stack, Orchestrate, and the multi-phase checklist, the guide paragraph in `docs/guide/06-verify-and-ship.md`, the `no-mistakes` line in `tools/cross-suite-foreign.txt`, and the `opening-a-pr-gated-publish-*` ledger promises with the `open-pr-gated-run` case.

diff --git a/README.md b/README.md
@@ -142,7 +142,7 @@ the full rules and playbooks live in [`skills/poteto-mode/SKILL.md`](./skills/po
 | [`/poteto-tdd`](./skills/poteto-tdd/SKILL.md) | you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix. |
 | [`/benchmark-checklist`](./skills/benchmark-checklist/SKILL.md) | you ran a benchmark or measured a speedup or regression. vets the number (limiter, tuning, errors, repeat runs, end-to-end relevance) before you report or act on it. |
 | [`/no-comments`](./skills/no-comments/SKILL.md) | strip comments before review; spawns Comment Sicko, fixes accepted findings, offers encodings for claimed constraints. |
-| [`/pr-recap`](./skills/pr-recap/SKILL.md) | (port addition) you opened or pushed to a pull request and want its reviewers to see the story first. posts one comment: two sentences on why and what, one hand-drawn sketch of the changed mechanism attached as an image, one line on what the PR does not prove, and a collapsed block with the risk, SHAs, and reading order. the sketch tool needs bun. Opening a PR runs it after each PR opens and after each push that changes the diff. its sources are credited in [`skills/pr-recap/CREDITS.md`](./skills/pr-recap/CREDITS.md). |
+| [`/pr-recap`](./skills/pr-recap/SKILL.md) | (port addition) you opened or pushed to a pull request and want its reviewers to see the story first. posts one comment: two sentences on why and what, one hand-drawn sketch of the changed mechanism attached as an image, one line on what the PR does not prove, and a collapsed block with the risk, SHAs, and reading order. the sketch tool needs bun. [Opening a PR](./skills/poteto-mode/playbooks/opening-a-pr.md) invokes it for a new PR. [Task triggers](./skills/poteto-mode/references/task-triggers.md) govern post-push refresh timing. its sources are credited in [`skills/pr-recap/CREDITS.md`](./skills/pr-recap/CREDITS.md). |
 | [`/deslop`](./skills/deslop/SKILL.md) | (port addition) you're about to commit and the diff reads padded. removes narrating comments, guards on impossible states, dead compatibility paths, one-caller wrappers, and unrelated edits from the changed hunks, then reruns the touched tests. a comment its rules don't settle goes through `/no-comments` in the same pass, and the report says what that review did. code only; `/unslop` is for prose. |
 | [`/typescript-best-practices`](./skills/typescript-best-practices/SKILL.md) | you're reading or editing typescript. grounds the type-system-discipline principle in syntax. |
 | [`/figure-it-out`](./skills/figure-it-out/SKILL.md) | no bundled playbook fits. designs a rigorous, auditable playbook for the task. |

diff --git a/skills/poteto-mode/playbooks/opening-a-pr.md b/skills/poteto-mode/playbooks/opening-a-pr.md
@@ -78,7 +78,7 @@ The URL check below is for github.com attachments and uses its token. For Enterp
 
 For upstream-sync publication routes and draft requirements, follow [Syncing from upstream](../../../PORTING.md#syncing-from-upstream).
 
-**Recap.** After a PR opens, and after each push that changes its diff, use the **pr-recap** skill.
+**Recap.** After a PR opens, use the **pr-recap** skill. For post-push refresh timing, follow [task triggers](../references/task-triggers.md).
 
 **Babysit.** Opening a PR does not start a babysit. Post the URL and keep building. Finish the phase or stack first. Run a separate babysit pass only when the user asks for one after the whole stack exists. A babysit for each new PR stalls the build and spends checks on commits later waves restart. Push back when feedback drifts from intent.
 

diff --git a/skills/poteto-mode/references/task-triggers.md b/skills/poteto-mode/references/task-triggers.md
@@ -18,6 +18,7 @@ Read this reference for the actions named by the mode entry, or when scope chang
 - Shipping UI / IDE / CLI → use the project's verification skill (`verify-<app>`, generated by the **create-verification-skill** skill), which drives the real surface — browser, Electron, web UI, CLI, or TUI. For bug fixes, reproduce first on the same surface yourself. Hand to the user only under the narrow Bug fix step 1 exception.
 - Running a benchmark, measuring perf yourself, or reporting a speedup or regression you measured → use the **benchmark-checklist** skill before you report or act on the number.
 - Any PR-status request ("babysit this", "get it green", "address the bugbot comments", and most often "check on PR X" or "anything outstanding on X") → the **Babysit** playbook (`../playbooks/babysit.md`), not any built-in babysit skill your CLI ships, even when its description matches the same words. Never triggered by merely opening a PR. Declare its mode before polling. The playbook's step 1 owns the request-to-mode mapping. Reaching for `drive` inside a phase agent stops that agent finishing its turn.
+- A push changed an open PR's diff, whether yours, an Autopilot owner's, a Babysit or Shipping wave, or a gate fix round → once the new head is published and any gate run has reached its outcome, use the **pr-recap** skill to refresh the PR's recap.
 - Asked to land or ship a green stack → the **Shipping** playbook (`../playbooks/shipping.md`). Green is not safe. Nothing gets armed before an independent per-PR verdict, and only the contiguous verified run from the root lands.
 - Bugbot, Copilot code review, GitHub Advanced Security, or another automated security reviewer commented → skeptical posture. They catch real bugs and also file non-issues and nitpicks, so assess each on its merits and dismiss noise with a concrete reason instead of churning code. Triage fix / dismiss / ask per `bugbot-triage.md`.
 - Broken skill mid-task → fix it in its own PR. Don't block. Don't silently work around it.

diff --git a/skills/pr-recap/SKILL.md b/skills/pr-recap/SKILL.md
@@ -11,13 +11,13 @@ Run this workflow locally. The recap is one PR comment: GitHub Markdown plus one
 
 ## Decide whether the PR gets a recap
 
-Skip the recap when the diff has no behavior that a reviewer must trace. Examples are a version pin and its hashes, a typo or wording fix, a formatting-only change, a lockfile-only change, and the revert of one commit.
+Skip the recap when the diff has no behavior that a reviewer must trace. Examples are a version pin and its hashes, a typo or wording fix, a formatting-only change, a lockfile-only change, and the revert of one commit. A version pin skips even across a major version, because a pin has no mechanism to sketch.
 
 For a skipped PR, post nothing on GitHub. Put one line in your reply:
 
 `Recap skipped for PR <n>: <what the diff is>, <why it needs no recap>.`
 
-Otherwise, write the recap. Write it again after each push that changes the diff.
+Otherwise, write the recap. Write it again after each push that changes the diff, once the new head is published and any gate run on it has reached its outcome.
 
 ## Gather the facts
 
@@ -64,7 +64,7 @@ When your runtime cannot run Bun, or cannot show you an image, skip the sketch.
 1. List each factual sentence in the recap and each label in the sketch.
 2. Check each one against a hunk of the diff or a SHA-pinned line. Mark it verified, corrected, unsupported, or unverifiable.
 3. Fix each corrected claim. Delete each unsupported or unverifiable claim, or rewrite it as a guess. Re-render the sketch if a label changed.
-4. Check each link. Pin source links to the recorded head SHA. Review and CI links must point at records on the PR, with CI runs on that head.
+4. Check each link. Pin source links to the recorded head SHA. Review and CI links must point at records on the PR, with CI runs on that head. Never link a bot's review, because watch-pr and merge-gate read a trusted comment that links one as acknowledging its findings.
 5. Read `headRefOid` again. If it moved, rebuild the recap from the new diff.
 
 Keep the marks in your notes, not in the comment. Report the counts in your reply.