pr-shepherd 0.5.2 → 0.7.0

package/bin/github/client.mjs

@@ -1,63 +1,27 @@
 /**
- * Thin wrapper around the `gh` CLI for GraphQL and REST calls.
+ * High-level GitHub client — wraps http.mts for application-level concerns.
+ *
+ * All GitHub I/O goes through native fetch (via http.mts); the `gh` CLI is no
+ * longer used for GitHub API calls, but may be invoked as an auth-token
+ * fallback via `gh auth token` when neither GH_TOKEN nor GITHUB_TOKEN is set.
  */
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
-import { loadConfig } from "../config/load.mjs";
+import { graphql as httpGraphql, rest } from "./http.mjs";
+import { PR_NUMBER_BY_BRANCH_QUERY } from "./queries.mjs";
 const execFile = promisify(execFileCb);
 // ---------------------------------------------------------------------------
-// GraphQL
+// GraphQL — thin re-exports so callers don't need to import http.mts directly
 // ---------------------------------------------------------------------------
+export { graphql, graphqlWithRateLimit } from "./http.mjs";
 /**
- * Execute a GraphQL query via `gh api graphql`.
- *
- * @param query   The full GraphQL query/mutation string.
- * @param vars    Key-value pairs forwarded as `-f key=value` or `-F key=value`.
- *                Numeric values are passed with `-F`; everything else with `-f`.
+ * Returns the current repo's owner and name by parsing `git remote get-url origin`.
+ * Handles https://, git@, and ssh:// remote URL formats.
  */
-export async function graphql(query, vars = {}) {
-    const args = buildGraphqlArgs(query, vars);
-    const raw = await runGh(args);
-    const parsed = JSON.parse(raw);
-    if (parsed.errors?.length) {
-        const messages = parsed.errors.map((e) => e.message).join("; ");
-        throw new Error(`GitHub GraphQL error: ${messages}`);
-    }
-    return { data: parsed.data };
-}
-/** Like {@link graphql} but also returns the `x-ratelimit-remaining` header. */
-export async function graphqlWithRateLimit(query, vars = {}) {
-    // --include must come after 'api' (it's a flag for `gh api`, not for `gh`).
-    const [api, ...extraArgs] = buildGraphqlArgs(query, vars);
-    const args = [api, "--include", ...extraArgs];
-    const raw = await runGh(args);
-    // `gh api -i` prepends HTTP headers before the JSON body.
-    // Handle both CRLF (\r\n\r\n) and LF-only (\n\n) header separators.
-    const crlfEnd = raw.indexOf("\r\n\r\n");
-    const lfEnd = raw.indexOf("\n\n");
-    const headerEnd = crlfEnd >= 0 ? crlfEnd : lfEnd;
-    const headerSection = headerEnd >= 0 ? raw.slice(0, headerEnd) : "";
-    const body = headerEnd >= 0 ? raw.slice(headerEnd + (crlfEnd >= 0 ? 4 : 2)) : raw;
-    const remaining = parseHeaderNumber(headerSection, "x-ratelimit-remaining");
-    const limit = parseHeaderNumber(headerSection, "x-ratelimit-limit");
-    const resetAt = parseHeaderNumber(headerSection, "x-ratelimit-reset");
-    const parsed = JSON.parse(body);
-    if (parsed.errors?.length) {
-        const messages = parsed.errors.map((e) => e.message).join("; ");
-        throw new Error(`GitHub GraphQL error: ${messages}`);
-    }
-    return {
-        data: parsed.data,
-        rateLimit: remaining !== null && limit !== null && resetAt !== null
-            ? { remaining, limit, resetAt }
-            : undefined,
-    };
-}
-/** Returns the current repo's owner and name from `gh repo view`. */
 export async function getRepoInfo() {
-    const raw = await runGh(["repo", "view", "--json", "owner,name"]);
-    const parsed = JSON.parse(raw);
-    return { owner: parsed.owner.login, name: parsed.name };
+    const { stdout } = await execFile("git", ["remote", "get-url", "origin"]);
+    const url = stdout.trim();
+    return parseRemoteUrl(url);
 }
 /**
  * Derives the PR number for the current HEAD branch.
@@ -66,87 +30,52 @@ export async function getRepoInfo() {
 export async function getCurrentPrNumber() {
     try {
         const branch = await getCurrentBranch();
-        // In detached HEAD state git returns "HEAD" — no branch name to look up.
         if (branch === "HEAD")
             return null;
-        const raw = await runGh([
-            "pr",
-            "list",
-            "--head",
-            branch,
-            "--json",
-            "number",
-            "--jq",
-            ".[0].number",
-        ]);
-        const trimmed = raw.trim();
-        if (!trimmed || trimmed === "null")
-            return null;
-        return parseInt(trimmed, 10);
+        const repo = await getRepoInfo();
+        const result = await httpGraphql(PR_NUMBER_BY_BRANCH_QUERY, { owner: repo.owner, repo: repo.name, branch });
+        return result.data.repository?.pullRequests.nodes[0]?.number ?? null;
     }
     catch {
         return null;
     }
 }
-async function getCurrentBranch() {
-    // Use git directly for branch name — gh doesn't expose it.
-    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
-    return stdout.trim();
-}
 /** Returns the `headRefOid` (commit SHA) of the given PR as reported by GitHub. */
 export async function getPrHeadSha(pr, owner, name) {
-    const raw = await runGh(["api", `repos/${owner}/${name}/pulls/${pr}`, "--jq", ".head.sha"]);
-    return raw.trim();
+    const data = await rest("GET", `/repos/${owner}/${name}/pulls/${pr}`);
+    return data.head.sha;
 }
 /**
- * Fetches `mergeable` and `mergeStateStatus` via the REST API (`gh pr view`).
+ * Fetches `mergeable` and `mergeStateStatus` via the REST API.
  *
  * Used as a fallback when the GraphQL API returns `UNKNOWN` for these fields —
  * a known GitHub quirk where GraphQL lags behind the REST layer.
  */
 export async function getMergeableState(pr, owner, repo) {
-    const raw = await runGh([
-        "pr",
-        "view",
-        String(pr),
-        "--repo",
-        `${owner}/${repo}`,
-        "--json",
-        "mergeable,mergeStateStatus",
-    ]);
-    const parsed = JSON.parse(raw);
-    return parsed;
+    const data = await rest("GET", `/repos/${owner}/${repo}/pulls/${pr}`);
+    const mergeable = data.mergeable === true ? "MERGEABLE" : data.mergeable === false ? "CONFLICTING" : "UNKNOWN";
+    const mergeStateStatus = data.mergeable_state.toUpperCase();
+    return { mergeable, mergeStateStatus };
 }
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-function buildGraphqlArgs(query, vars) {
-    const args = ["api", "graphql", "-f", `query=${query}`];
-    for (const [k, v] of Object.entries(vars)) {
-        if (typeof v === "number" || typeof v === "boolean") {
-            args.push("-F", `${k}=${String(v)}`);
-        }
-        else {
-            args.push("-f", `${k}=${v}`);
-        }
-    }
-    return args;
+async function getCurrentBranch() {
+    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+    return stdout.trim();
 }
-async function runGh(args) {
-    try {
-        const { stdout } = await execFile("gh", args, {
-            maxBuffer: loadConfig().execution.maxBufferMb * 1024 * 1024,
-        });
-        return stdout;
+function parseRemoteUrl(url) {
+    // Strip trailing .git and trailing slash
+    const stripped = url.replace(/\.git$/, "").replace(/\/$/, "");
+    // ssh: git@host:owner/repo
+    const sshMatch = /^git@[^:]+:([^/]+)\/(.+)$/.exec(stripped);
+    if (sshMatch) {
+        return { owner: sshMatch[1], name: sshMatch[2] };
     }
-    catch (err) {
-        // Re-throw with a more useful message
-        const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`gh ${args[0] ?? ""} failed: ${msg}`, { cause: err });
+    // https or ssh://: https://host/owner/repo  or  ssh://git@host/owner/repo
+    const httpsMatch = /^(?:https?|ssh):\/\/[^/]+\/([^/]+)\/(.+)$/.exec(stripped);
+    if (httpsMatch) {
+        return { owner: httpsMatch[1], name: httpsMatch[2] };
     }
-}
-function parseHeaderNumber(headers, name) {
-    const re = new RegExp(`^${name}:\\s*(\\d+)`, "im");
-    const m = re.exec(headers);
-    return m ? parseInt(m[1], 10) : null;
+    throw new Error(`Cannot parse GitHub remote URL: ${url}`);
 }

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

@@ -5,10 +5,12 @@ query BatchPr(
   $threadsCursor: String
   $checksCursor: String
   $commentsCursor: String
-  $reviewsCursor: String
+  $changesRequestedCursor: String
+  $reviewSummariesCursor: String
 ) {
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
+      id
       number
       state
       isDraft
@@ -16,6 +18,7 @@ query BatchPr(
       mergeStateStatus
       reviewDecision
       headRefOid
+      baseRefName
       # Not paginated — capped at 50; PRs with more pending reviewers truncate silently.
       reviewRequests(last: 50) {
         nodes {
@@ -80,7 +83,11 @@ query BatchPr(
           createdAt
         }
       }
-      reviews(states: CHANGES_REQUESTED, last: 50, before: $reviewsCursor) {
+      changesRequestedReviews: reviews(
+        states: CHANGES_REQUESTED
+        last: 50
+        before: $changesRequestedCursor
+      ) {
         pageInfo {
           hasPreviousPage
           startCursor
@@ -93,6 +100,20 @@ query BatchPr(
           body
         }
       }
+      reviewSummaries: reviews(states: COMMENTED, last: 50, before: $reviewSummariesCursor) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          isMinimized
+          author {
+            login
+          }
+          body
+        }
+      }
       commits(last: 1) {
         nodes {
           commit {

package/bin/github/gql/mark-pr-ready.gql

@@ -0,0 +1,7 @@
+mutation MarkPrReady($pullRequestId: ID!) {
+  markPullRequestReadyForReview(input: { pullRequestId: $pullRequestId }) {
+    pullRequest {
+      isDraft
+    }
+  }
+}

package/bin/github/gql/pr-number-by-branch.gql

@@ -0,0 +1,9 @@
+query PrNumberByBranch($owner: String!, $repo: String!, $branch: String!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequests(headRefName: $branch, states: OPEN, first: 1) {
+      nodes {
+        number
+      }
+    }
+  }
+}

package/bin/github/http.mjs

@@ -0,0 +1,145 @@
+/**
+ * Thin native-fetch HTTP client for the GitHub API.
+ * Replaces the previous `gh` CLI shell-out on every code path.
+ *
+ * Token resolution order:
+ *   1. GH_TOKEN env
+ *   2. GITHUB_TOKEN env
+ *   3. `gh auth token` (fallback for users who have run `gh auth login`)
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+const execFile = promisify(execFileCb);
+const BASE_URL = "https://api.github.com";
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+let _token;
+export function _resetTokenCache() {
+    _token = undefined;
+}
+async function resolveToken() {
+    if (_token)
+        return _token;
+    if (process.env["GH_TOKEN"]) {
+        _token = process.env["GH_TOKEN"];
+        return _token;
+    }
+    if (process.env["GITHUB_TOKEN"]) {
+        _token = process.env["GITHUB_TOKEN"];
+        return _token;
+    }
+    try {
+        const { stdout } = await execFile("gh", ["auth", "token"]);
+        const token = stdout.trim();
+        if (token) {
+            _token = token;
+            return _token;
+        }
+    }
+    catch {
+        // fall through to error
+    }
+    throw new Error("No GitHub token found. Set GH_TOKEN or GITHUB_TOKEN, or run `gh auth login`.");
+}
+async function makeHeaders() {
+    return {
+        Authorization: `Bearer ${await resolveToken()}`,
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "pr-shepherd",
+        "Content-Type": "application/json",
+    };
+}
+// ---------------------------------------------------------------------------
+// GraphQL
+// ---------------------------------------------------------------------------
+async function graphqlInner(query, vars) {
+    const res = await fetch(`${BASE_URL}/graphql`, {
+        method: "POST",
+        headers: await makeHeaders(),
+        body: JSON.stringify({ query, variables: vars }),
+    });
+    const rateLimit = parseRateLimit(res.headers);
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`GitHub GraphQL request failed: ${res.status} ${body.slice(0, 300)}`);
+    }
+    const parsed = (await res.json());
+    if (parsed.errors?.length) {
+        const messages = parsed.errors.map((e) => e.message).join("; ");
+        throw new Error(`GitHub GraphQL error: ${messages}`);
+    }
+    return { data: parsed.data, rateLimit };
+}
+export async function graphql(query, vars = {}) {
+    const { data } = await graphqlInner(query, vars);
+    return { data };
+}
+export async function graphqlWithRateLimit(query, vars = {}) {
+    const { data, rateLimit } = await graphqlInner(query, vars);
+    return { data, rateLimit: rateLimit ?? undefined };
+}
+// ---------------------------------------------------------------------------
+// REST
+// ---------------------------------------------------------------------------
+export async function rest(method, path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers: await makeHeaders(),
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`GitHub REST ${method} ${path} failed: ${res.status} ${text.slice(0, 300)}`);
+    }
+    const ct = res.headers.get("content-type") ?? "";
+    if (ct.includes("application/json")) {
+        return res.json();
+    }
+    return undefined;
+}
+/**
+ * GET request that returns plain text.
+ * Handles the 302 redirect pattern used by the GitHub Actions job-logs endpoint —
+ * the redirect target (a signed storage URL) is fetched without auth headers.
+ */
+export async function restText(path) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: "GET",
+        headers: await makeHeaders(),
+        redirect: "manual",
+    });
+    if (res.status === 301 || res.status === 302 || res.status === 307 || res.status === 308) {
+        const location = res.headers.get("location");
+        if (location) {
+            const redirectRes = await fetch(location);
+            if (!redirectRes.ok) {
+                throw new Error(`redirect target ${location} failed: ${redirectRes.status}`);
+            }
+            return redirectRes.text();
+        }
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`GitHub REST GET ${path} failed: ${res.status} ${text.slice(0, 300)}`);
+    }
+    return res.text();
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function parseRateLimit(headers) {
+    const rRaw = headers.get("x-ratelimit-remaining");
+    const lRaw = headers.get("x-ratelimit-limit");
+    const tRaw = headers.get("x-ratelimit-reset");
+    if (rRaw === null || lRaw === null || tRaw === null)
+        return null;
+    const remaining = Number(rRaw);
+    const limit = Number(lRaw);
+    const resetAt = Number(tRaw);
+    if (Number.isFinite(remaining) && Number.isFinite(limit) && Number.isFinite(resetAt)) {
+        return { remaining, limit, resetAt };
+    }
+    return null;
+}

package/bin/github/queries.mjs

@@ -19,3 +19,7 @@ export const DISMISS_REVIEW_MUTATION = gql("dismiss-review.gql");
 export const MULTI_PR_STATUS_QUERY = gql("multi-pr-status.gql");
 /** Paginated version — used when reviewThreads is truncated (totalCount > 100). */
 export const MULTI_PR_STATUS_QUERY_WITH_CURSOR = gql("multi-pr-status-paged.gql");
+/** Look up PR number by branch name (for getCurrentPrNumber). */
+export const PR_NUMBER_BY_BRANCH_QUERY = gql("pr-number-by-branch.gql");
+/** Convert a draft PR to ready for review. */
+export const MARK_PR_READY_MUTATION = gql("mark-pr-ready.gql");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",

package/plugin/skills/monitor/SKILL.md

@@ -9,24 +9,18 @@ allowed-tools:
 
 # pr-shepherd monitor — Continuous PR Monitor
 
+> Action reference (all 8 actions, JSON fields, examples): [docs/actions.md](../../../docs/actions.md)
+
 ## Arguments: $ARGUMENTS
 
 ## Resolve PR number
 
 1. Strip any trailing `every <N> <unit>` interval clause from `$ARGUMENTS` first.
-2. Extract `--ready-delay <duration>` if present (e.g. `--ready-delay 15m`). Default: `10m`.
+2. Extract `--ready-delay <duration>` if present (e.g. `--ready-delay 15m`). Default: `10m`. Keep the raw duration string (e.g. `10m`) — do **not** convert to seconds.
 3. If the remaining text contains a PR number or GitHub PR URL, extract the number.
 4. Otherwise, infer: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
 5. If no PR found, report an error and stop.
 
-## Detect base branch
-
-```bash
-BASE_BRANCH=$(gh pr view <PR_NUMBER> --json baseRefName --jq '.baseRefName')
-```
-
-Default to `main` if the command fails.
-
 ## Start the loop
 
 **Before starting:** List existing cron jobs with `CronList`.
@@ -39,63 +33,26 @@ Invoke `/loop <INTERVAL> --max-turns 50 --expires 8h` via the Skill tool. Use th
 
 ````
 # pr-shepherd-loop:pr=<PR_NUMBER>
-Run the following in a single Bash invocation:
-  npx pr-shepherd iterate <PR_NUMBER> --ready-delay <READY_DELAY> --no-cache --last-push-time "$(git log -1 --format=%ct HEAD)" --format=json
-
-Exit codes 0, 1, 2, and 3 are all valid signals — always try to parse stdout as JSON first. If the command exits non-zero and stdout is not parseable JSON (e.g. a crash), log the first line of stderr and continue (do not cancel the loop).
-
-Parse the `action` field and act:
-
-- `cooldown` → log: `SKIP: CI still starting`
-- `wait` → log: `WAIT: <summary.passing> passing, <summary.inProgress> in-progress (merge state: <mergeStateStatus>, <remainingSeconds>s cooldown remaining)`
-- `rerun_ci` → log: `RERAN <N> CI checks: <reran joined by space>`
-- `mark_ready` → log: `MARKED READY: PR <pr>`
-- `cancel` → invoke `/loop cancel` and stop
-- `rebase` → run:
-  ```bash
-  if ! git diff --quiet || ! git diff --cached --quiet; then
-    echo "SKIP rebase: dirty worktree (uncommitted changes present)"
-    exit 0
-  fi
-  git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease
-  ```
-
-- `escalate` → invoke `/loop cancel` via Skill tool, then print:
-
-  ⚠️ /pr-shepherd:monitor paused — needs human direction
-
-  Triggers: <escalate.triggers joined by ", ">
-  <escalate.suggestion>
-
-  Items needing attention:
-  <for each thread in escalate.unresolvedThreads: "- threadId=<id> <path ?? '(no location)'>:<line ?? '?'> (@<author>): <body first line>">
-  <if escalate.changesRequestedReviews.length > 0: for each "- reviewId=<id> (@<author>): <body first line>">
-  <if escalate.attemptHistory: "Fix attempts: " + each "threadId=<id> attempted <N> times">
-
-  Run /pr-shepherd:check <PR> to see current state.
-  After fixing manually, rerun /pr-shepherd:monitor <PR> to resume.
-
-- `fix_code` → do the following, then stop this iteration (CI needs time):
-  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`, 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. If files were changed: `git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease`, 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. 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.
+
+**IMPORTANT — recurrence rules:**
+- **Do NOT call `ScheduleWakeup` or `/loop`.** This session is fired by a recurring cron job. Either call creates a duplicate runner, causing concurrent git operations and `.git/index.lock` collisions.
+- End the turn cleanly after completing the actions below. The cron job handles the next fire.
+
+**Self-dedup:** Run `CronList`. If more than one job contains `# pr-shepherd-loop:pr=<PR_NUMBER>`, keep the lowest job ID and `CronDelete` the rest (ignore errors — a concurrent runner may have already deleted them).
+
+Run in a single Bash call:
+  npx pr-shepherd iterate <PR_NUMBER> --ready-delay <READY_DELAY_DURATION> --no-cache --last-push-time "$(git log -1 --format=%ct HEAD)"
+(`<READY_DELAY_DURATION>` is the raw duration string, e.g. `10m` — never a bare number of seconds)
+
+Exit codes 0–3 are all valid. If the command crashes (non-zero exit, no markdown output starting with `# PR #<N> [`), log the first line of stderr and continue — do not cancel the loop. The next cron fire will retry.
+
+The output is Markdown. The first line is an H1 heading of the form `# PR #<N> [<ACTION>]`. Read the `[<ACTION>]` tag to decide what to do (see [docs/actions.md](../../../docs/actions.md) for full output shapes):
+
+- `[COOLDOWN]` | `[WAIT]` | `[RERUN_CI]` | `[MARK_READY]` → print the output, continue.
+- `[CANCEL]`   → print the output, then invoke `/loop cancel` via Skill tool and stop.
+- `[REBASE]`   → print the output, then extract the shell script from the ` ```bash ` fenced block and run it in Bash.
+- `[ESCALATE]` → print the output, then invoke `/loop cancel` via Skill tool and stop.
+- `[FIX_CODE]` → follow the numbered items under `## Instructions` in order. Only run a `resolve` command if those instructions explicitly include a "Run the `resolve:` command…" step, or if the provided resolve command includes mutation flags. In that case, the `resolve` bullet under `## Rebase` holds the final resolve command inside backticks — strip the backticks and run it, substituting `"$HEAD_SHA"` with the pushed SHA and `$DISMISS_MESSAGE` with a one-sentence description of the actual fix (never generic text like "address review comments"). **Never manually run `gh run cancel` after your push** — stale runs listed under `## Cancelled runs` were already cancelled by the CLI (using the pre-push run IDs, as required by the "cancel CI runs before fixing and pushing" rule); running it again post-push would hit the NEW runs your push just triggered. If you run the resolve command, stop this iteration afterward — CI needs time before the next tick.
 
 ````
 
@@ -111,7 +68,7 @@ The default 4-minute interval is chosen for two reasons:
 The loop prompt above handles each iteration directly — no subagent is spawned. The same iterate command can be run manually at any time:
 
 ```bash
-npx pr-shepherd iterate <PR_NUMBER> --ready-delay <READY_DELAY> --no-cache --last-push-time "$(git log -1 --format=%ct HEAD)" --format=json
+npx pr-shepherd iterate <PR_NUMBER> --ready-delay <READY_DELAY_DURATION> --no-cache --last-push-time "$(git log -1 --format=%ct HEAD)"
 ```
 
 To stop monitoring manually, use `/loop cancel` or close the session.

package/plugin/skills/resolve/SKILL.md

@@ -44,12 +44,18 @@ Resolve unresolved review threads and minimize PR comments on the current PR —
    ```
 
    The CLI auto-resolves outdated threads.
-   Parse the JSON for `actionableThreads`, `actionableComments`, `changesRequestedReviews`.
+   Parse the JSON for `actionableThreads`, `actionableComments`, `changesRequestedReviews`, `reviewSummaries`.
 
-3. **Triage each actionable item.** For each unresolved thread or visible comment:
-   - Read the comment body to understand what it's asking
-   - For review threads: read the referenced file and line
-   - Classify as: **Fixed** (already addressed), **Not relevant**, **Outdated**, or **Actionable** (real issue, not yet fixed)
+3. **Triage each actionable item** into exactly one of these five buckets. Before classifying, read the comment body and — for threads — the referenced file and line.
+   - **Fixed** — already addressed in a prior commit; no new work needed.
+   - **Actionable** — real issue, not yet fixed; proceed to step 4.
+   - **Not relevant** — does not apply to this PR (e.g. comment is about unrelated code).
+   - **Outdated** — refers to code that no longer exists.
+   - **Acknowledge** — real comment, intentionally not acting on it (e.g. reviewer flagged it as "won't fix" or "not worth it," scope-out decision, deferring to a follow-up PR). Record the one-sentence reason — you will include it in the step 7 report so the user can override.
+
+   Every item returned by step 2 **must** land in one of these buckets. Do not carry an item forward as "unclassified" or silently skip it. If you genuinely can't decide, that's the Acknowledge bucket with reason "unclear — flagging for human review."
+
+   **Review summaries** (`reviewSummaries`): these are PR-level overview bodies from COMMENTED reviews. Bot-generated summaries (authors like `copilot-pull-request-reviewer`, `gemini-code-assist`, or other bot accounts) are almost always noise — default them to **Acknowledge** with reason "bot summary — no actionable content" unless the body explicitly calls out an unaddressed issue. Human-authored review summaries should be read carefully and classified like any other item.
 
 4. **Fix actionable items.** For each Actionable item:
    - Read the relevant file(s) and apply the fix (Edit/Write tools)
@@ -59,29 +65,38 @@ Resolve unresolved review threads and minimize PR comments on the current PR —
 5. **Commit and push** (only if code was changed):
    - `git add <file1> <file2> …` (NOT `git add -A`)
    - `git commit -m "<appropriate commit message>"`
+   - If the fixes alter the PR's scope or intent, run `gh pr edit <N> --title "<new title>" --body "<new body>"` to keep the PR title and description in sync with what was committed. Skip if the existing text still accurately describes the 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, 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:
+6. **Resolve all verified items** — **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. For Fixed items, this step runs only after the push; Acknowledge / Not relevant / Outdated items can be resolved without a push (and therefore without `--require-sha`).
+
+   Each bucket maps to a mutation flag:
+   - **Fixed** threads → `--resolve-thread-ids`; Fixed comments → `--minimize-comment-ids`; Fixed reviews (CHANGES_REQUESTED) → `--dismiss-review-ids --message "<what you changed>"`.
+   - **Acknowledge / Not relevant / Outdated** threads → `--resolve-thread-ids`; same-bucket comments → `--minimize-comment-ids`; same-bucket reviews (CHANGES_REQUESTED) → `--dismiss-review-ids --message "<why you're not acting>"`.
+   - **Review summaries** in any bucket (Fixed, Acknowledge, Not relevant, Outdated) → `--minimize-comment-ids`. Review summary IDs (`PRR_…` from `reviewSummaries`) are passed here, not to `--dismiss-review-ids`. Do not pass review summary IDs to `--dismiss-review-ids` — that flag is only for CHANGES_REQUESTED reviews.
 
    ```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 "<specific description of the fix that addressed this review>" \
+     --message "<specific description of the fix OR the reason you're not acting>" \
      --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.
+   `--message` belongs **only** with `--dismiss-review-ids`. Omit it entirely when not dismissing a review. When you are dismissing, write one sentence — either describing the actual fix (for Fixed) or the concrete reason for not acting (for Acknowledge). 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.
+
+   Include `--require-sha $(git rev-parse HEAD)` whenever a push happened in step 5 (it gates the whole command, not per-item — safe to mix Fixed and Acknowledge IDs under one `--require-sha`). Omit it when no code changed.
 
-   The `--require-sha` flag ensures pr-shepherd verifies GitHub has the new commit before resolving.
+7. **Report results.** Echo the CLI's output, then append a one-line summary per Acknowledge item: `Acknowledged <threadId|commentId|reviewId> (@<author>): <reason>`. This surfaces the decisions so the user can override any that were wrong.
 
-7. **Report results** from the CLI output.
+   If any fetched item was neither resolved nor acknowledged (step 3 is supposed to prevent this, but guard against it), **stop and escalate** to the user: `<N> item(s) fetched but not acted on or acknowledged — need human direction before closing`. Do not silently drop items.
 
 ## Rules
 
-- NEVER resolve threads before pushing fixes (use `--require-sha`).
+- NEVER resolve **Fixed** threads before pushing the fix (use `--require-sha`). Acknowledge / Not relevant / Outdated do not require a push and omit `--require-sha`.
 - NEVER blindly resolve items — always read and verify first.
+- NEVER silently skip a fetched item. Every item must be resolved, acknowledged with a reason, or escalated.
 - Resolve from ALL authors — bots, AI reviewers, and humans alike.
-- `--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.
+- `--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 or the concrete reason for not acting (e.g. `"Added null check in handler.ts:42"`, or `"Acknowledged as won't-fix — reviewer noted not worth refactoring"`); generic boilerplate like `"address review comments"` or `"Addressed in <SHA>"` is reviewer-hostile and forbidden.