pr-shepherd 0.44.0 → 0.45.0

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -28,7 +28,7 @@ mechanics every tick. Apply the referenced playbook in full whenever a step poin
 ### Suggestion patches
 
 - Run one plural `build-suggestion-patches` command with a repeated `--thread-id … --message … [--description …]` group for every marked thread in displayed order.
-- The CLI only builds patches. Apply, stage, and commit the returned patches in order. Push only when authorization has been established outside Shepherd; GitHub viewer fields cannot verify the local Git credential.
+- The CLI only builds patches. Apply, stage, and commit the returned patches in order. This command does not itself check push authorization — follow the `iterate`/`fix_code` output's own commit/push instruction for whether to push now or hand off: it reflects whether GitHub confirms the viewer can push to the PR head branch.
 - The command builds from the fetched PR head and accepts a clean local descendant only when the complete ordered patch stream passes `git apply --check`.
 - If the command refuses because a suggestion is unsafe or no longer applies, inspect the current source, the displayed replacement block, and reviewer intent before editing manually. Do not apply a stale numeric range blindly or retry unchanged input.
 - A returned patch was checked against the then-current worktree. If it later fails, re-inspect the worktree because it changed after validation.
@@ -40,14 +40,19 @@ Match each failure's `[conclusion: …]` tag under `## Failing checks` to a rule
 
 More specific rows win over the general "GitHub Actions failure" row — check conclusion first.
 
-| Tag / kind                                                               | Do                                                                                                                                                                                                |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt if one is rendered. If it is missing or insufficient, hand off the displayed run ID/URL; Shepherd cannot verify authorization for another Actions read or mutation. |
-| Transient infrastructure failure                                         | Record the diagnosis. Shepherd does not recommend a rerun because GitHub exposes no exact viewer capability for that workflow-run action.                                                         |
-| Real test or build failure                                               | Apply a code fix — do not rerun.                                                                                                                                                                  |
-| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered. Hand off the displayed metadata; Shepherd cannot verify authorization for another Actions read or mutation.                                                           |
-| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered. Hand off the displayed metadata; Shepherd cannot verify authorization for another Actions read or mutation.                                                           |
-| `external` (no run ID, has a URL)                                        | Preserve the URL in the handoff. Shepherd does not recommend opening it because it cannot verify the current viewer's access to the external system.                                              |
+A `[rerun authorized]` tag with a `rerun:` command means the viewer's repository role grants GitHub's Actions rerun capability (WRITE+) — Shepherd verified this from `repositoryPermission`. This confirms the account's role, not the granular scope of whatever credential actually runs `gh`; if the printed `rerun:` command still fails when run, do not retry it — hand off the displayed metadata instead, the same as an unauthorized check. No tag/command means Shepherd could not verify the account-level capability at all; hand off instead of guessing. A run still in progress, an `ACTION_REQUIRED` run (paused pending manual workflow approval — a rerun cannot grant that approval), or a check whose runId does not resolve to a GitHub Actions workflow never gets `[rerun authorized]`, regardless of role.
+
+When several bullets share one runId (matrix jobs from the same run), the `rerun:` command is printed once, on the first bullet; every bullet for that runId still carries `[rerun authorized]` and is covered by that single command — do not run it more than once.
+
+| Tag / kind                                                               | Do                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt if one is rendered. If it is missing or insufficient: run the `rerun:` command if `[rerun authorized]`, then iterate again once it completes; otherwise hand off the displayed run ID/URL. |
+| Transient infrastructure failure                                         | Run the `rerun:` command if `[rerun authorized]`, then iterate again once it completes. Otherwise record the diagnosis and hand off — Shepherd cannot verify rerun authorization.                                        |
+| Real test or build failure                                               | Apply a code fix — do not rerun, even if `[rerun authorized]` is shown.                                                                                                                                                  |
+| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered. Run the `rerun:` command if `[rerun authorized]`, then iterate again once it completes; otherwise hand off the displayed metadata.                                                           |
+| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered. Run the `rerun:` command if `[rerun authorized]`, then iterate again once it completes; otherwise hand off the displayed metadata.                                                           |
+| `[conclusion: ACTION_REQUIRED]`                                          | Never carries `[rerun authorized]`. Hand off — the run needs a maintainer's manual workflow approval on GitHub, which a rerun cannot grant.                                                                              |
+| `external` (no run ID, has a URL)                                        | Preserve the URL in the handoff. Shepherd does not recommend opening it because it cannot verify the current viewer's access to the external system.                                                                     |
 
 ### Review-mutation mechanics