pr-shepherd 0.4.1 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "pr-shepherd",
       "description": "Autonomous PR CI monitor and review-comment resolver",
-      "source": "./.claude-plugin",
+      "source": "./plugin",
       "category": "productivity",
       "homepage": "https://github.com/jonathanong/pr-shepherd"
     }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -21,6 +21,22 @@ Autonomous PR CI monitor and review-comment resolver for Claude Code.
 
 ## Install
 
+> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. The skills invoke `npx pr-shepherd`, so you also need the CLI available. If you're using `pr-shepherd` as development tooling for your repo, install it as a dev dependency so `npx` resolves it without prompting:
+>
+> ```bash
+> npm install --save-dev pr-shepherd
+> ```
+>
+> A plain `npm install pr-shepherd` adds it to regular dependencies instead; use that only if you specifically want it under `dependencies`. Or install globally: `npm install -g pr-shepherd`.
+
+### As individual skills via `npx skills`
+
+```bash
+npx skills add jonathanong/pr-shepherd
+```
+
+Installs the three skills (`check`, `monitor`, `resolve`) into your agent's skill directory (`.claude/skills/` for project scope, `~/.claude/skills/` with `-g` for global scope). Powered by [skills.sh](https://skills.sh).
+
 ### As a Claude Code plugin (recommended)
 
 ```bash
@@ -149,14 +165,160 @@ pr-shepherd iterate [PR] [--cooldown-seconds N] [--ready-delay Nm] [--last-push-
 pr-shepherd status PR1 [PR2 …]                        # multi-PR table
 ```
 
-Common flags:
+Common flags (all subcommands):
+
+| Flag                  | Default | Description                                                                    |
+| --------------------- | ------- | ------------------------------------------------------------------------------ |
+| `--format text\|json` | `text`  | Output format                                                                  |
+| `--no-cache`          | false   | Bypass the 5-minute file cache                                                 |
+| `--cache-ttl N`       | `300`   | Cache TTL in seconds; `PR_SHEPHERD_CACHE_TTL_SECONDS` env var takes precedence |
+
+### pr-shepherd check [PR]
+
+Read-only PR status snapshot. Fetches CI results, merge state, and review comments in one GraphQL batch. PR number is inferred from the current branch when omitted.
+
+```sh
+pr-shepherd check           # infer PR from current branch
+pr-shepherd check 42
+pr-shepherd check 42 --format=json
+pr-shepherd check 42 --no-cache
+```
+
+Exit codes: `0` READY · `2` IN_PROGRESS · `3` UNRESOLVED_COMMENTS · `1` all other statuses
+
+**Example output:**
+
+```
+PR #42 — owner/repo
+Status: UNRESOLVED_COMMENTS
+
+Merge Status: CLEAN
+  mergeStateStatus:       CLEAN
+  mergeable:              MERGEABLE
+  reviewDecision:         APPROVED
+  isDraft:                false
+  copilotReviewInProgress:false
+
+CI Checks: 3/3 passed
+
+Actionable Review Threads (1):
+  - threadId=RT_kwDOBxyz123 src/api.ts:47 (@reviewer)
+    Please add error handling here
+
+Summary: 1 actionable item(s) remaining
+```
+
+### pr-shepherd resolve [PR]
+
+Two modes: **fetch** (default) auto-resolves outdated threads and returns actionable items; **mutate** resolves/minimizes/dismisses specific IDs after you push fixes.
+
+**Fetch mode:**
+
+```sh
+pr-shepherd resolve           # fetch + auto-resolve outdated threads
+pr-shepherd resolve 42 --fetch --format=json
+```
+
+```
+Actionable Review Threads (2):
+  - threadId=RT_kwDOabc src/api.ts:47 (@reviewer): Please add error handling here
+  - threadId=RT_kwDOdef src/utils.ts:12 (@bot): Consider using a const here
+
+Summary: 2 actionable item(s)
+```
+
+**Mutate mode** (after pushing fixes):
+
+```sh
+pr-shepherd resolve 42 \
+  --resolve-thread-ids RT_kwDOabc,RT_kwDOdef \
+  --minimize-comment-ids IC_kwDOxyz \
+  --dismiss-review-ids PRR_kwDO123 \
+  --message "Switched query to parameterized form in src/db.ts" \
+  --require-sha $(git rev-parse HEAD)
+```
+
+```
+Resolved threads (2): RT_kwDOabc, RT_kwDOdef
+Minimized comments (1): IC_kwDOxyz
+Dismissed reviews (1): PRR_kwDO123
+```
+
+`--require-sha` polls GitHub until the PR head matches the SHA before mutating — ensures reviewers see the fix before threads are closed. Exit code: always `0`. `--message` is required only when `--dismiss-review-ids` is set, and should describe the specific fix — it is shown to the reviewer on GitHub.
+
+### pr-shepherd iterate [PR]
+
+One monitor tick: classifies current PR state and emits a single action. Used by the cron loop; the monitor skill calls this every 4 minutes and acts on the result. See [docs/iterate-flow.md](docs/iterate-flow.md) for the full decision tree.
+
+```sh
+pr-shepherd iterate 42 --no-cache --format=json \
+  --ready-delay 10m \
+  --last-push-time "$(git log -1 --format=%ct HEAD)"
+```
+
+Flags:
+
+| Flag                          | Default | Description                                       |
+| ----------------------------- | ------- | ------------------------------------------------- |
+| `--ready-delay Nm`            | `10m`   | Settle window before the loop cancels after READY |
+| `--cooldown-seconds N`        | `30`    | Wait after a push before reading CI               |
+| `--last-push-time N`          | —       | Unix timestamp hint embedded in the result        |
+| `--no-auto-rerun`             | false   | Return `wait` instead of rerunning transient CI   |
+| `--no-auto-mark-ready`        | false   | Skip converting draft → ready-for-review          |
+| `--no-auto-cancel-actionable` | false   | Skip cancelling actionable failing runs           |
+
+**Text output** (one line per action):
+
+```
+PR #42 [COOLDOWN] status=UNKNOWN merge=UNKNOWN (cooldown: CI still starting)
+PR #42 [WAIT] status=READY merge=CLEAN (540s until cancel)
+PR #42 [RERUN_CI] status=FAILING merge=UNSTABLE reran=12345,67890
+PR #42 [FIX_CODE] status=UNRESOLVED_COMMENTS merge=BLOCKED threads=2 comments=0 checks=1 cancelled=1
+PR #42 [REBASE] status=FAILING merge=BEHIND (branch is behind main)
+PR #42 [MARK_READY] status=READY merge=CLEAN markedReady=true
+PR #42 [CANCEL] status=READY merge=CLEAN (ready-delay elapsed)
+PR #42 [ESCALATE] status=UNRESOLVED_COMMENTS merge=BLOCKED triggers=fix-thrash — Same thread(s) attempted multiple times without resolution — fix manually then rerun /pr-shepherd:monitor
+```
+
+**JSON output** (`--format=json`, compact single line):
+
+```json
+{
+  "pr": 42,
+  "repo": "owner/repo",
+  "status": "READY",
+  "state": "OPEN",
+  "mergeStateStatus": "CLEAN",
+  "copilotReviewInProgress": false,
+  "isDraft": false,
+  "shouldCancel": false,
+  "remainingSeconds": 540,
+  "summary": { "passing": 3, "skipped": 0, "filtered": 0, "inProgress": 0 },
+  "action": "wait"
+}
+```
+
+Exit codes: `0` wait/cooldown/rerun_ci/mark_ready · `1` fix_code/rebase · `2` cancel · `3` escalate
+
+### pr-shepherd status PR1 [PR2 …]
+
+Multi-PR summary table. One lightweight GraphQL query per PR, run in parallel.
+
+```sh
+pr-shepherd status 41 42 43
+pr-shepherd status 100 --format=json
+```
+
+```
+
+# owner/repo — PR status (3)
+
+PR #41    Add new feature for user authentication           READY        SUCCESS
+PR #42    Refactor internal module                          IN PROGRESS  PENDING
+PR #43    Fix edge case in parser                           BLOCKED      SUCCESS (threads truncated — run shepherd check for full count)
+```
 
-| Flag                  | Default | Description                     |
-| --------------------- | ------- | ------------------------------- |
-| `--format text\|json` | `text`  | Output format                   |
-| `--no-cache`          | false   | Bypass the 5-minute file cache  |
-| `--cache-ttl N`       | 300     | Cache TTL in seconds            |
-| `--ready-delay Nm`    | `10m`   | Settle window before loop exits |
+Exit code: `0` if every PR is READY, `1` otherwise.
 
 ## Configuration
 
@@ -178,7 +340,7 @@ See [docs/configuration.md](docs/configuration.md) for all options.
 
 ## Requirements
 
-- Node.js ≥ 24.0.0
+- Node.js ≥ 22.0.0
 - `gh` CLI authenticated (`gh auth login`); `repo` scope is required for private repositories (public repositories may not need it)
 - `git`
 

package/bin/commands/check.mjs

@@ -62,7 +62,7 @@ export async function runCheck(opts) {
     // Triage failures (fetch logs) — skipped when caller will short-circuit before needing failureKind.
     const triaged = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing) : failing;
     // Resolve threads and comments.
-    const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved);
+    const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = batchData.comments.filter((c) => !c.isMinimized);
     // Auto-resolve outdated threads.
     const outdated = getOutdatedThreads(unresolvedThreads);

package/bin/commands/resolve.mjs

@@ -28,7 +28,7 @@ export async function runResolveFetch(opts) {
     }
     // Always bypass cache for resolve — we need fresh data before mutating.
     const { data } = await fetchPrBatch(prNumber, repo);
-    const unresolvedThreads = data.reviewThreads.filter((t) => !t.isResolved);
+    const unresolvedThreads = data.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = data.comments.filter((c) => !c.isMinimized);
     // Auto-resolve outdated.
     const outdated = getOutdatedThreads(unresolvedThreads);

package/bin/github/batch.mjs

@@ -117,6 +117,7 @@ function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawChe
             id: t.id,
             isResolved: t.isResolved,
             isOutdated: t.isOutdated,
+            isMinimized: comment?.isMinimized ?? false,
             path: comment?.path ?? null,
             line: comment?.line ?? null,
             author: comment?.author?.login ?? "unknown",

package/bin/github/gql/batch-pr.gql

@@ -53,6 +53,7 @@ query BatchPr(
           comments(first: 1) {
             nodes {
               id
+              isMinimized
               author {
                 login
               }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -10,7 +10,7 @@
   },
   "files": [
     "bin/**",
-    "skills/**",
+    "plugin/**",
     ".claude-plugin/**",
     "marketplace.json",
     "README.md",
@@ -35,9 +35,9 @@
     "prepare": "npm run build",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "typecheck": "tsc --noEmit",
-    "lint": "oxlint src/ skills/",
-    "format": "oxfmt src/ skills/ docs/ README.md",
-    "format:check": "oxfmt --check src/ skills/ docs/ README.md",
+    "lint": "oxlint src/ plugin/skills/",
+    "format": "oxfmt src/ plugin/skills/ docs/ README.md",
+    "format:check": "oxfmt --check src/ plugin/skills/ docs/ README.md",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest"

package/{skills → plugin/skills}/monitor/SKILL.md

@@ -76,15 +76,26 @@ Parse the `action` field and act:
   After fixing manually, rerun /pr-shepherd:monitor <PR> to resume.
 
 - `fix_code` → do the following, then stop this iteration (CI needs time):
-  1. For each item in `fix.threads` and `fix.comments`: read the referenced file/line and apply the fix (Edit/Write tools).
+  0. **Triage `fix.comments`** into two buckets before taking any action:
+     - **Noise** (`NOISE_COMMENT_IDS`): bot-authored comments with no actionable code feedback — e.g. quota/rate-limit warnings ("you have reached your daily quota", "please wait up to N hours"), "resuming" notices, bare acknowledgements, or any comment whose body contains no file path, line number, or concrete code suggestion. Collect their `id`s.
+     - **Actionable**: everything else. When in doubt, treat as actionable.
+     All items in `fix.threads` are always actionable (they carry a file path and line by construction).
+  1. For each item in `fix.threads` and each **actionable** `fix.comments`: read the referenced file/line and apply the fix (Edit/Write tools).
   2. For each item in `fix.checks`:
      - If `runId` is non-null: fetch the failure log with `gh run view <runId> --log-failed` (dangerouslyDisableSandbox: true), scan the output to identify the failure (e.g. grep for `FAIL` for test failures, `error:` for type/compile errors, lint rule names for lint failures), then read the relevant file and apply the fix (Edit/Write tools).
      - If `runId` is null: the failed check is an external status check that cannot be inspected via run logs. Escalate — tell the user to open `detailsUrl` in the PR checks UI, inspect the failure manually, and rerun `/pr-shepherd:monitor <PR_NUMBER>` after addressing it. Do not attempt to fix these automatically.
   3. For each item in `fix.changesRequestedReviews`: read the review body and apply the requested changes.
   4. If files were changed, `git add <files> && git commit -m "<appropriate commit message>"`
-  5. `git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease` (dangerouslyDisableSandbox: true)
-  6. `HEAD_SHA=$(git rev-parse HEAD)`
-  7. `npx pr-shepherd resolve <PR_NUMBER> --resolve-thread-ids <IDs> --minimize-comment-ids <IDs> --dismiss-review-ids <IDs> --message "address review comments" --require-sha "$HEAD_SHA"` (dangerouslyDisableSandbox: true). Omit any flag whose ID list is empty.
+  5. If files were changed: `git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease` (dangerouslyDisableSandbox: true), then `HEAD_SHA=$(git rev-parse HEAD)`.
+  6. If **only noise** was found (no files changed, no threads/checks/reviews to act on): skip commit/push and omit `--require-sha` in the next step.
+  7. Resolve the items on GitHub (dangerouslyDisableSandbox: true). Build the command from the non-empty ID lists only — always start with:
+     `npx pr-shepherd resolve <PR_NUMBER>`
+     Then append:
+     - `--resolve-thread-ids <IDs>` only if `fix.threads` was non-empty.
+     - `--minimize-comment-ids <IDs>` if any comments exist (use `NOISE_COMMENT_IDS` plus IDs of any other comments to minimize).
+     - `--dismiss-review-ids <IDs> --message "<specific description of what you changed>"` only if `fix.changesRequestedReviews` was non-empty. The message is shown to the reviewer on GitHub — write one sentence describing the actual fix (e.g. `"Switched to parameterized query in src/db.ts"`). Never use generic text like `"address review comments"`.
+     - `--require-sha "$HEAD_SHA"` only if a push occurred (omit when only noise was handled).
+     Omit any flag whose ID list is empty.
 
 ````
 

package/{skills → plugin/skills}/resolve/SKILL.md

@@ -62,17 +62,19 @@ Resolve unresolved review threads and minimize PR comments on the current PR —
    - `git fetch origin && git rebase origin/$BASE_BRANCH && git push --force-with-lease`
    - Cancel stale CI runs: `gh run list --branch "$BRANCH" --status in_progress --json databaseId --jq '.[].databaseId' | xargs -I{} gh run cancel {}`
 
-6. **Resolve all verified items** — **only after the push:**
+6. **Resolve all verified items** — **only after the push, and only if at least one of the three ID lists is non-empty.** If all lists are empty, skip this step entirely (running resolve with no mutation IDs enters fetch mode as a side effect). Build the command from the non-empty ID lists; omit any flag whose list is empty:
 
    ```bash
    npx pr-shepherd resolve <N> \
      --resolve-thread-ids <comma-separated-IDs> \
      --minimize-comment-ids <comma-separated-IDs> \
      --dismiss-review-ids <comma-separated-IDs> \
-     --message "Addressed in $(git rev-parse HEAD)" \
+     --message "<specific description of the fix that addressed this review>" \
      --require-sha $(git rev-parse HEAD)
    ```
 
+   `--message` belongs **only** with `--dismiss-review-ids`. Omit it entirely when not dismissing a review. When you are dismissing, write one sentence describing the actual fix — the text is sent to GitHub as the dismissal reason and is shown to the reviewer. Generic text like `"Addressed in <SHA>"` or `"address review comments"` is not acceptable.
+
    The `--require-sha` flag ensures pr-shepherd verifies GitHub has the new commit before resolving.
 
 7. **Report results** from the CLI output.
@@ -82,4 +84,4 @@ Resolve unresolved review threads and minimize PR comments on the current PR —
 - NEVER resolve threads before pushing fixes (use `--require-sha`).
 - NEVER blindly resolve items — always read and verify first.
 - Resolve from ALL authors — bots, AI reviewers, and humans alike.
-- `--message` is required when using `--dismiss-review-ids`. The CLI will throw if it is missing.
+- `--message` is required when using `--dismiss-review-ids`, and must NOT be passed otherwise. The CLI throws if it is missing during dismissal. The message must describe the specific change that addressed the review (e.g. `"Added null check in handler.ts:42"`); generic boilerplate like `"address review comments"` or `"Addressed in <SHA>"` is reviewer-hostile and forbidden.