pr-shepherd 0.46.4 → 0.46.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +2 -2
- package/bin/cli/api-usage-formatter.mjs +1 -1
- package/bin/cli/iterate-instructions.mjs +3 -3
- package/bin/commands/iterate/check-instructions.mjs +4 -4
- package/bin/commands/iterate/render.mjs +2 -2
- package/bin/quota-warning.mjs +1 -1
- package/package.json +1 -1
- package/plugins/pr-shepherd/.codex-plugin/plugin.json +1 -1
- package/plugins/pr-shepherd/.codex.mcp.json +1 -1
- package/plugins/pr-shepherd/.mcp.json +1 -1
- package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md +11 -11
package/README.md
CHANGED
|
@@ -69,12 +69,12 @@ Conversations Resolved: No [Not Required]
|
|
|
69
69
|
1. Review each item under `## Review threads` and `## Failing checks` and decide whether it needs a code change.
|
|
70
70
|
2. Apply every warranted review fix in each file referenced above.
|
|
71
71
|
3. Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for read-only inspection rules.
|
|
72
|
-
4. If you changed code, commit any remaining changes and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate
|
|
72
|
+
4. If you changed code, commit any remaining changes and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate immediately with the same options. If you did not change code, do not commit and continue.
|
|
73
73
|
5. Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an earlier Shepherd reply: a marked viewer-authored human thread is emitted resolve-only when authorized, while a marked other-human thread is already acknowledged and has no further mutation.
|
|
74
74
|
6. If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, commit and push to the PR head branch first, then replace `$HEAD_SHA` with the pushed commit SHA.
|
|
75
75
|
7. Replace `$DISMISS_MESSAGE` with one sentence describing what changed.
|
|
76
76
|
8. Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.
|
|
77
|
-
9. `[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate
|
|
77
|
+
9. `[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate immediately with the same options; without code changes, complete the authorized review mutations and iterate immediately.
|
|
78
78
|
```
|
|
79
79
|
|
|
80
80
|
See [docs/actions.md](docs/actions.md) for the complete output contract and [docs/escalations.md](docs/escalations.md) for the exact finite human-handoff boundary. Iterate/poll PR outcomes use exit codes `0` and `10`–`15`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
|
|
@@ -18,7 +18,7 @@ export function formatQuotaWarning(warning) {
|
|
|
18
18
|
`- Reset: ${resetTime(warning.resetAt)}`,
|
|
19
19
|
`- Recommended poll interval: ${warning.pollIntervalMinutes} minutes`,
|
|
20
20
|
`- Recommended bounded CLI timeout: ${warning.pollTimeoutMinutes} minutes`,
|
|
21
|
-
"- Recommendation:
|
|
21
|
+
"- Recommendation: keep polling pr-shepherd at the cadence above; for incidental PR operations prefer REST `gh` (`gh pr view`, `gh pr review`, `gh api`); do not substitute `gh pr checks`/`gh pr watch`",
|
|
22
22
|
].join("\n");
|
|
23
23
|
}
|
|
24
24
|
export function formatApiUsage(usage) {
|
|
@@ -10,7 +10,7 @@ export function buildSimpleIterateInstructions(result) {
|
|
|
10
10
|
];
|
|
11
11
|
}
|
|
12
12
|
return [
|
|
13
|
-
"Non-terminal — no action needed this tick. Iterate
|
|
13
|
+
"Non-terminal — no action needed this tick. Iterate immediately with the same options to continue.",
|
|
14
14
|
];
|
|
15
15
|
case "mark_ready":
|
|
16
16
|
if (result.quotaWarning) {
|
|
@@ -19,7 +19,7 @@ export function buildSimpleIterateInstructions(result) {
|
|
|
19
19
|
];
|
|
20
20
|
}
|
|
21
21
|
return [
|
|
22
|
-
"The CLI marked the PR ready for review. Iterate
|
|
22
|
+
"The CLI marked the PR ready for review. Iterate immediately with the same options to continue.",
|
|
23
23
|
];
|
|
24
24
|
case "merge": {
|
|
25
25
|
const instructions = [
|
|
@@ -33,7 +33,7 @@ export function buildSimpleIterateInstructions(result) {
|
|
|
33
33
|
}
|
|
34
34
|
instructions.push(result.quotaWarning
|
|
35
35
|
? buildQuotaAwareContinuation(result.quotaWarning, "After running the merge command.")
|
|
36
|
-
: "Then iterate
|
|
36
|
+
: "Then iterate immediately with the same options to monitor until the PR merges or needs work.");
|
|
37
37
|
return instructions;
|
|
38
38
|
}
|
|
39
39
|
case "cancel":
|
|
@@ -90,12 +90,12 @@ export function buildFailingCheckInstructions(checks) {
|
|
|
90
90
|
}
|
|
91
91
|
export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false) {
|
|
92
92
|
if (hasConflicts)
|
|
93
|
-
return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate
|
|
93
|
+
return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate immediately with the same options.";
|
|
94
94
|
if (hasShaGatedReviewMutations) {
|
|
95
|
-
return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate
|
|
95
|
+
return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate immediately with the same options; if you did not change code, complete the authorized review mutations and iterate immediately with the same options.";
|
|
96
96
|
}
|
|
97
97
|
if (checks.some((check) => check.rerunCommand)) {
|
|
98
|
-
return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate
|
|
98
|
+
return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate immediately with the same options to continue.";
|
|
99
99
|
}
|
|
100
|
-
return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate
|
|
100
|
+
return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate immediately with the same options to continue.";
|
|
101
101
|
}
|
|
@@ -96,10 +96,10 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
|
|
|
96
96
|
instructions.push(`Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`);
|
|
97
97
|
}
|
|
98
98
|
else if (hasRepeatedWorkflowBranchRecovery) {
|
|
99
|
-
instructions.push("Push the updated PR head branch before iterating
|
|
99
|
+
instructions.push("Push the updated PR head branch before iterating immediately.");
|
|
100
100
|
}
|
|
101
101
|
else if (hasNonConflictHints) {
|
|
102
|
-
instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate
|
|
102
|
+
instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate immediately with the same options. If you did not change code, do not commit and continue with the remaining steps.");
|
|
103
103
|
}
|
|
104
104
|
if (viewerCanUpdate &&
|
|
105
105
|
(hasReviewMutations ||
|
package/bin/quota-warning.mjs
CHANGED
|
@@ -2,5 +2,5 @@ export function buildQuotaAwareContinuation(warning, prefix) {
|
|
|
2
2
|
const interval = `${warning.pollIntervalMinutes}m`;
|
|
3
3
|
const timeout = `${warning.pollTimeoutMinutes}m`;
|
|
4
4
|
const resetTime = new Date(warning.resetAt * 1000).toISOString();
|
|
5
|
-
return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold).
|
|
5
|
+
return `${prefix} GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool. Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, replace any existing interval and timeout flags with \`--interval ${interval} --timeout ${timeout}\`, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
|
|
6
6
|
}
|
package/package.json
CHANGED
|
@@ -8,7 +8,7 @@ allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob", "Edit", "Write"]
|
|
|
8
8
|
|
|
9
9
|
# pr-shepherd
|
|
10
10
|
|
|
11
|
-
Thin dispatcher for creating or iterating a PR. Poll with the CLI; use MCP `iterate` only when the CLI is unavailable.
|
|
11
|
+
Thin dispatcher for creating or iterating a PR. Poll with the CLI; use MCP `iterate` only when the CLI is unavailable. Keep invoking until `[CANCEL]` or `[ESCALATE]`. Do not wait for CI to finish before the next Shepherd step — fetching check logs is fine; blocking on `gh pr checks`, `gh pr watch`, `gh run watch`, or equivalent GitHub MCP check waiters is not. Shepherd already returns CI plus review comments, and waiting for CI before applying review feedback wastes CI.
|
|
12
12
|
|
|
13
13
|
## PR creation authorization
|
|
14
14
|
|
|
@@ -24,7 +24,7 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
|
|
|
24
24
|
|
|
25
25
|
3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.
|
|
26
26
|
|
|
27
|
-
4. After completing the returned instructions, repeat step 2 with the same target and canonical options unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. Preserve `--until-terminal` and any requested `--merge`; apply any polling-cadence adjustment printed by the CLI. Every other action is non-terminal: complete its instructions and rerun without asking whether to continue. `[FIX_CODE]` is always non-terminal, and only `[ESCALATE]` hands work to a human.
|
|
27
|
+
4. After completing the returned instructions, immediately repeat step 2 with the same target and canonical options unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. Preserve `--until-terminal` and any requested `--merge`; apply any polling-cadence adjustment printed by the CLI. Every other action is non-terminal: complete its instructions and rerun without asking whether to continue. `[FIX_CODE]` is always non-terminal, and only `[ESCALATE]` hands work to a human. After a push or `rerun:`, do not wait for CI to finish first — you may pull check logs, but do not poll with `gh pr checks`, `gh pr watch`, `gh run watch`, or equivalent GitHub MCP check waiters.
|
|
28
28
|
|
|
29
29
|
## Playbooks
|
|
30
30
|
|
|
@@ -50,15 +50,15 @@ A `[rerun authorized]` tag with a `rerun:` command means the viewer's repository
|
|
|
50
50
|
|
|
51
51
|
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.
|
|
52
52
|
|
|
53
|
-
| Tag / kind | Do
|
|
54
|
-
| ------------------------------------------------------------------------ |
|
|
55
|
-
| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt. Apply a warranted code fix, or run the printed `rerun:` command when the evidence indicates a transient failure, then iterate
|
|
56
|
-
| Transient infrastructure failure | Run the `rerun:` command when present, then iterate
|
|
57
|
-
| Real test or build failure | Apply a code fix — do not rerun, even if `[rerun authorized]` is shown.
|
|
58
|
-
| `[conclusion: CANCELLED]` | No log excerpt is rendered. Run the printed `rerun:` command, then iterate
|
|
59
|
-
| `[conclusion: STARTUP_FAILURE]` | No log excerpt is rendered. Run the printed `rerun:` command, then iterate
|
|
60
|
-
| `[conclusion: ACTION_REQUIRED]` | This appears in `[FIX_CODE]` only alongside other autonomous work. Complete that work and iterate; Shepherd returns `[ESCALATE]` if manual workflow approval remains necessary.
|
|
61
|
-
| `external` (no run ID, has a URL) | Treat the URL as an autonomous investigation path: inspect the provider or reproduce the failure locally, apply any warranted fix, and iterate. A non-empty external URL does not trigger `[ESCALATE]` by itself.
|
|
53
|
+
| Tag / kind | Do |
|
|
54
|
+
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt. Apply a warranted code fix, or run the printed `rerun:` command when the evidence indicates a transient failure, then iterate immediately. Missing autonomous follow-up becomes `[ESCALATE]` when no other work remains. |
|
|
56
|
+
| Transient infrastructure failure | Run the `rerun:` command when present, then iterate immediately. Do not wait for the rerun to finish. If no command is present, complete any other surfaced work and iterate; Shepherd owns any later `[ESCALATE]`. |
|
|
57
|
+
| Real test or build failure | Apply a code fix — do not rerun, even if `[rerun authorized]` is shown. |
|
|
58
|
+
| `[conclusion: CANCELLED]` | No log excerpt is rendered. Run the printed `rerun:` command, then iterate immediately. Do not wait for the rerun to finish. Without a command, complete any other work and iterate; Shepherd escalates when this remains the only blocker. |
|
|
59
|
+
| `[conclusion: STARTUP_FAILURE]` | No log excerpt is rendered. Run the printed `rerun:` command, then iterate immediately. Do not wait for the rerun to finish. Without a command, complete any other work and iterate; Shepherd escalates when this remains the only blocker. |
|
|
60
|
+
| `[conclusion: ACTION_REQUIRED]` | This appears in `[FIX_CODE]` only alongside other autonomous work. Complete that work and iterate; Shepherd returns `[ESCALATE]` if manual workflow approval remains necessary. |
|
|
61
|
+
| `external` (no run ID, has a URL) | Treat the URL as an autonomous investigation path: inspect the provider or reproduce the failure locally, apply any warranted fix, and iterate. A non-empty external URL does not trigger `[ESCALATE]` by itself. |
|
|
62
62
|
|
|
63
63
|
### Review-mutation mechanics
|
|
64
64
|
|