pr-shepherd 0.3.0 → 0.4.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "jonathanong",
+  "description": "Jonathan Ong's Claude Code plugins",
+  "owner": {
+    "name": "Jonathan Ong",
+    "email": "jonathanrichardong@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "pr-shepherd",
+      "description": "Autonomous PR CI monitor and review-comment resolver",
+      "source": "./.claude-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.3.0",
+  "version": "0.4.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -28,6 +28,8 @@ claude /plugin marketplace add jonathanong/pr-shepherd
 claude /plugin install pr-shepherd
 ```
 
+This repo ships two `marketplace.json` files that serve different install flows: the root `marketplace.json` resolves the plugin from the npm registry (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
+
 See [Usage](#usage) below.
 
 ### Without the plugin — custom slash command

package/{dist → bin}/cache/file-cache.mjs

@@ -36,7 +36,8 @@ export async function cacheGet(key, opts = {}) {
     }
 }
 /**
- * Write a value to the cache (fire-and-forget — never throws).
+ * Write a value to the cache. Errors are swallowed — callers can await
+ * to know when the write is done, but the write never rejects.
  */
 export async function cacheSet(key, value, opts = {}) {
     if (opts.disabled)

package/{dist → bin}/cli/args.mjs

@@ -2,9 +2,11 @@
  * CLI argument-parsing helpers extracted from cli.mts for testability.
  * Note: parseCommonArgs calls loadConfig() for cache TTL defaults.
  */
+import { parseArgs } from "node:util";
 import { loadConfig } from "../config/load.mjs";
 import { deriveVerdict } from "../commands/status.mjs";
-// Flags that consume the next argument as their value.
+// Flags that consume the next argument as their value (used for PR-number
+// detection only — prevents a flag's value from being mistaken for a PR number).
 const FLAGS_WITH_VALUES = new Set([
     "--format",
     "--cache-ttl",
@@ -14,33 +16,54 @@ const FLAGS_WITH_VALUES = new Set([
     "--require-sha",
     "--message",
 ]);
+// ---------------------------------------------------------------------------
+// Strict integer parsing
+// ---------------------------------------------------------------------------
+export function parseIntStrict(value, flag) {
+    if (!/^-?\d+$/.test(value.trim())) {
+        throw new Error(`Invalid value for ${flag}: "${value}" is not an integer`);
+    }
+    return parseInt(value, 10);
+}
 export function parseCommonArgs(args) {
     const config = loadConfig();
-    const format = (getFlag(args, "--format") ?? "text");
-    const noCache = hasFlag(args, "--no-cache");
-    const cacheTtlStr = getFlag(args, "--cache-ttl");
-    const cacheTtlSeconds = cacheTtlStr ? parseInt(cacheTtlStr, 10) : config.cache.ttlSeconds;
-    // Only global flags are stripped from `extra`; subcommand-specific flags
-    // must remain so handlers like handleIterate/handleResolve can read them.
-    const globalFlagsWithValues = new Set(["--format", "--cache-ttl"]);
-    const skipForPrDetect = new Set(); // indices to skip when finding PR number
-    const excludeFromExtra = new Set(); // indices to strip from extra (global only)
-    for (let i = 0; i < args.length; i += 1) {
-        const arg = args[i];
-        if (arg === "--no-cache") {
-            skipForPrDetect.add(i);
-            excludeFromExtra.add(i);
-        }
-        else if (globalFlagsWithValues.has(arg)) {
-            skipForPrDetect.add(i);
-            excludeFromExtra.add(i);
-            if (i + 1 < args.length) {
-                skipForPrDetect.add(i + 1);
-                excludeFromExtra.add(i + 1);
+    const { values, tokens } = parseArgs({
+        args,
+        strict: false,
+        allowPositionals: true,
+        tokens: true,
+        options: {
+            format: { type: "string" },
+            "cache-ttl": { type: "string" },
+            "no-cache": { type: "boolean" },
+        },
+    });
+    const format = (values.format ?? "text");
+    const noCache = (values["no-cache"] ?? false);
+    const cacheTtlStr = values["cache-ttl"];
+    const cacheTtlSeconds = cacheTtlStr
+        ? parseIntStrict(cacheTtlStr, "--cache-ttl")
+        : config.cache.ttlSeconds;
+    // Build the set of arg indices consumed by global flags so we can strip
+    // them from `extra`.  Subcommand-specific flags are left untouched.
+    const consumedIndices = new Set();
+    for (const tok of tokens ?? []) {
+        if (tok.kind === "option" &&
+            (tok.name === "format" || tok.name === "cache-ttl" || tok.name === "no-cache")) {
+            consumedIndices.add(tok.index);
+            // When the value is a separate arg (--flag value, not --flag=value),
+            // inlineValue is false and the value occupies tok.index + 1.
+            if ("inlineValue" in tok && tok.inlineValue === false && tok.value != null) {
+                consumedIndices.add(tok.index + 1);
             }
-            i += 1;
         }
-        else if (FLAGS_WITH_VALUES.has(arg)) {
+    }
+    // Find the first positional arg that looks like a PR number, skipping values
+    // that belong to flags in FLAGS_WITH_VALUES (subcommand flags included).
+    const skipForPrDetect = new Set();
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (FLAGS_WITH_VALUES.has(arg)) {
             skipForPrDetect.add(i);
             if (i + 1 < args.length)
                 skipForPrDetect.add(i + 1);
@@ -48,21 +71,18 @@ export function parseCommonArgs(args) {
         }
         else {
             const eqIdx = arg.indexOf("=");
-            if (eqIdx > 0) {
-                const flagName = arg.slice(0, eqIdx);
-                if (FLAGS_WITH_VALUES.has(flagName)) {
-                    skipForPrDetect.add(i);
-                    if (globalFlagsWithValues.has(flagName))
-                        excludeFromExtra.add(i);
-                }
+            if (eqIdx > 0 && FLAGS_WITH_VALUES.has(arg.slice(0, eqIdx))) {
+                skipForPrDetect.add(i);
             }
         }
     }
-    // First non-skipped positional arg that looks like a PR number.
-    const prArg = args.find((a, index) => !skipForPrDetect.has(index) && !a.startsWith("--") && /^\d+$/.test(a));
-    const prNumber = prArg ? parseInt(prArg, 10) : undefined;
-    // Only strip global flags from extra — subcommand flags are passed through.
-    const extra = args.filter((_, index) => !excludeFromExtra.has(index));
+    const prIndex = args.findIndex((a, index) => !skipForPrDetect.has(index) && !a.startsWith("--") && /^\d+$/.test(a));
+    const prNumber = prIndex !== -1 ? parseInt(args[prIndex], 10) : undefined;
+    // Remove consumed global-flag indices (and the PR number itself) from extra.
+    if (prIndex !== -1) {
+        consumedIndices.add(prIndex);
+    }
+    const extra = args.filter((_, i) => !consumedIndices.has(i));
     return {
         prNumber,
         global: { format, noCache, cacheTtlSeconds },

package/{dist → bin}/cli.mjs

@@ -17,7 +17,7 @@ import { getRepoInfo } from "./github/client.mjs";
 import { formatJson } from "./reporters/json.mjs";
 import { formatText } from "./reporters/text.mjs";
 import { loadConfig } from "./config/load.mjs";
-import { parseCommonArgs, getFlag, hasFlag, parseList, parseStatusPrNumbers, parseDurationToMinutes, statusToExitCode, iterateActionToExitCode, deriveSimpleReady, } from "./cli/args.mjs";
+import { parseCommonArgs, getFlag, hasFlag, parseList, parseStatusPrNumbers, parseDurationToMinutes, parseIntStrict, statusToExitCode, iterateActionToExitCode, deriveSimpleReady, } from "./cli/args.mjs";
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
@@ -40,7 +40,8 @@ export async function main(argv) {
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
             process.stderr.write("Usage: pr-shepherd <check|resolve|iterate|status> [options]\n");
-            process.exit(1);
+            process.exitCode = 1;
+            return;
     }
 }
 // ---------------------------------------------------------------------------
@@ -51,7 +52,8 @@ async function handleCheck(args) {
     const report = await runCheck({ ...globalOpts, prNumber, autoResolve: false });
     const output = globalOpts.format === "json" ? formatJson(report) : formatText(report);
     process.stdout.write(`${output}\n`);
-    process.exit(statusToExitCode(report.status));
+    process.exitCode = statusToExitCode(report.status);
+    return;
 }
 async function handleResolve(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
@@ -88,13 +90,15 @@ async function handleResolve(args) {
 async function handleIterate(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const lastPushTimeStr = getFlag(extra, "--last-push-time");
-    const lastPushTime = lastPushTimeStr ? parseInt(lastPushTimeStr, 10) : undefined;
+    const lastPushTime = lastPushTimeStr
+        ? parseIntStrict(lastPushTimeStr, "--last-push-time")
+        : undefined;
     const readyDelayStr = getFlag(extra, "--ready-delay");
     const cfg = loadConfig();
     const readyDelaySeconds = parseDurationToMinutes(readyDelayStr ?? "", cfg.watch.readyDelayMinutes) * 60;
     const cooldownSecondsStr = getFlag(extra, "--cooldown-seconds");
     const cooldownSeconds = cooldownSecondsStr
-        ? parseInt(cooldownSecondsStr, 10)
+        ? parseIntStrict(cooldownSecondsStr, "--cooldown-seconds")
         : cfg.iterate.cooldownSeconds;
     const noAutoRerun = hasFlag(extra, "--no-auto-rerun");
     const noAutoMarkReady = hasFlag(extra, "--no-auto-mark-ready");
@@ -115,14 +119,16 @@ async function handleIterate(args) {
     else {
         process.stdout.write(`${formatIterateResult(result)}\n`);
     }
-    process.exit(iterateActionToExitCode(result.action));
+    process.exitCode = iterateActionToExitCode(result.action);
+    return;
 }
 async function handleStatus(args) {
     const { global: globalOpts } = parseCommonArgs(args);
     const prNumbers = parseStatusPrNumbers(args);
     if (prNumbers.length === 0) {
         process.stderr.write("Usage: pr-shepherd status PR1 [PR2 …]\n");
-        process.exit(1);
+        process.exitCode = 1;
+        return;
     }
     const repo = await getRepoInfo();
     const summaries = await runStatus({ ...globalOpts, prNumbers });
@@ -131,19 +137,14 @@ async function handleStatus(args) {
         : formatStatusTable(summaries, `${repo.owner}/${repo.name}`);
     process.stdout.write(`${output}\n`);
     const allReady = summaries.every((s) => deriveSimpleReady(s));
-    process.exit(allReady ? 0 : 1);
+    process.exitCode = allReady ? 0 : 1;
+    return;
 }
 // ---------------------------------------------------------------------------
 // Output formatters
 // ---------------------------------------------------------------------------
 function formatFetchResult(result) {
     const lines = [];
-    if (result.autoResolved.length > 0) {
-        lines.push(`Auto-resolved outdated (${result.autoResolved.length}):`);
-        for (const t of result.autoResolved) {
-            lines.push(`  - threadId=${t.id} ${t.path ?? ""}:${t.line ?? "?"} (@${t.author})`);
-        }
-    }
     if (result.actionableThreads.length > 0) {
         lines.push(`\nActionable Review Threads (${result.actionableThreads.length}):`);
         for (const t of result.actionableThreads) {

package/{dist → bin}/commands/iterate.mjs

@@ -88,6 +88,9 @@ export async function runIterate(opts) {
     }
     // Step 3: Ready-delay state machine.
     const [repoOwner, repoName] = report.repo.split("/");
+    if (!repoOwner || !repoName) {
+        throw new Error(`Unexpected repo format: "${report.repo}" (expected "owner/name")`);
+    }
     const isReady = report.status === "READY";
     const readyState = await updateReadyDelay(report.pr, isReady, readyDelaySeconds, repoOwner, repoName);
     const base = {
@@ -239,6 +242,9 @@ async function tryCancelRun(runId) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
+        // gh returns this when the run reached a terminal state — expected, not worth logging.
+        if (/already completed|cannot cancel a workflow run that is completed/i.test(msg))
+            return null;
         process.stderr.write(`pr-shepherd: gh run cancel ${runId} failed (ignored): ${msg}\n`);
         return null;
     }

package/{dist → bin}/commands/resolve.mjs

@@ -32,15 +32,15 @@ export async function runResolveFetch(opts) {
     const visibleComments = data.comments.filter((c) => !c.isMinimized);
     // Auto-resolve outdated.
     const outdated = getOutdatedThreads(unresolvedThreads);
-    let autoResolved = [];
     if (outdated.length > 0) {
-        const { resolved: resolvedIds } = await autoResolveOutdated(outdated.map((t) => t.id));
-        autoResolved = outdated.filter((t) => resolvedIds.includes(t.id));
+        const { errors } = await autoResolveOutdated(outdated.map((t) => t.id));
+        if (errors.length > 0) {
+            throw new Error(`Failed to auto-resolve outdated threads: ${errors.join(", ")}`);
+        }
     }
     const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated);
     return {
-        autoResolved,
-        actionableThreads: activeThreads,
+        actionableThreads: activeThreads.map(({ isResolved, isOutdated, ...rest }) => rest),
         actionableComments: visibleComments,
         changesRequestedReviews: data.changesRequestedReviews,
     };

package/{dist → bin}/comments/resolve.mjs

@@ -14,10 +14,6 @@
 import { graphql, getPrHeadSha } from "../github/client.mjs";
 import { RESOLVE_THREAD_MUTATION, MINIMIZE_COMMENT_MUTATION, DISMISS_REVIEW_MUTATION, } from "../github/queries.mjs";
 import { loadConfig } from "../config/load.mjs";
-const config = loadConfig();
-const CONCURRENCY = config.resolve.concurrency;
-const SHA_POLL_INTERVAL_MS = config.resolve.shaPoll.intervalMs;
-const SHA_POLL_MAX_ATTEMPTS = config.resolve.shaPoll.maxAttempts;
 /**
  * Execute all requested resolve/minimize/dismiss mutations.
  *
@@ -69,6 +65,7 @@ async function dismissReview(reviewId, message) {
 // Concurrency helper
 // ---------------------------------------------------------------------------
 async function runBatched(ids, fn, successList, errorList) {
+    const CONCURRENCY = loadConfig().resolve.concurrency;
     // Process in chunks of CONCURRENCY.
     for (let i = 0; i < ids.length; i += CONCURRENCY) {
         const chunk = ids.slice(i, i + CONCURRENCY);
@@ -88,6 +85,7 @@ async function runBatched(ids, fn, successList, errorList) {
 // SHA polling
 // ---------------------------------------------------------------------------
 async function waitForSha(pr, repo, expectedSha) {
+    const { intervalMs: SHA_POLL_INTERVAL_MS, maxAttempts: SHA_POLL_MAX_ATTEMPTS } = loadConfig().resolve.shaPoll;
     for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
         try {
             // eslint-disable-next-line no-await-in-loop

package/{dist → bin}/config/load.mjs

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { parse } from "yaml";
@@ -9,13 +9,9 @@ function findRcFile(startDir) {
     let current = startDir;
     while (true) {
         const candidate = join(current, RC_FILENAME);
-        try {
-            readFileSync(candidate);
+        if (statSync(candidate, { throwIfNoEntry: false })?.isFile()) {
             return candidate;
         }
-        catch {
-            // not found here
-        }
         if (current === home || current === dirname(current))
             return null;
         current = dirname(current);
@@ -56,7 +52,10 @@ function applyCompat(raw) {
     const iterate = out["iterate"];
     if (iterate && "maxFixAttempts" in iterate) {
         process.stderr.write(`pr-shepherd: config key "iterate.maxFixAttempts" renamed to "iterate.fixAttemptsPerThread".\n`);
-        out["iterate"] = { fixAttemptsPerThread: iterate["maxFixAttempts"], ...iterate };
+        out["iterate"] = {
+            ...iterate,
+            fixAttemptsPerThread: iterate["fixAttemptsPerThread"] ?? iterate["maxFixAttempts"],
+        };
         delete out["iterate"]["maxFixAttempts"];
     }
     // Renamed watch keys
@@ -65,17 +64,18 @@ function applyCompat(raw) {
         const watchOut = { ...watch };
         if ("intervalDefault" in watch) {
             process.stderr.write(`pr-shepherd: config key "watch.intervalDefault" renamed to "watch.interval".\n`);
-            watchOut["interval"] = watch["intervalDefault"];
+            watchOut["interval"] = watchOut["interval"] ?? watch["intervalDefault"];
             delete watchOut["intervalDefault"];
         }
         if ("readyDelayMinutesDefault" in watch) {
             process.stderr.write(`pr-shepherd: config key "watch.readyDelayMinutesDefault" renamed to "watch.readyDelayMinutes".\n`);
-            watchOut["readyDelayMinutes"] = watch["readyDelayMinutesDefault"];
+            watchOut["readyDelayMinutes"] =
+                watchOut["readyDelayMinutes"] ?? watch["readyDelayMinutesDefault"];
             delete watchOut["readyDelayMinutesDefault"];
         }
         if ("expiresHoursDefault" in watch) {
             process.stderr.write(`pr-shepherd: config key "watch.expiresHoursDefault" renamed to "watch.expiresHours".\n`);
-            watchOut["expiresHours"] = watch["expiresHoursDefault"];
+            watchOut["expiresHours"] = watchOut["expiresHours"] ?? watch["expiresHoursDefault"];
             delete watchOut["expiresHoursDefault"];
         }
         out["watch"] = watchOut;
@@ -88,13 +88,17 @@ function applyCompat(raw) {
         let shaPollChanged = false;
         if ("shaPollIntervalMs" in resolve) {
             process.stderr.write(`pr-shepherd: config key "resolve.shaPollIntervalMs" moved to "resolve.shaPoll.intervalMs".\n`);
-            shaPollOut["intervalMs"] = resolve["shaPollIntervalMs"];
+            shaPollOut["intervalMs"] =
+                resolve["shaPoll"]?.["intervalMs"] ??
+                    resolve["shaPollIntervalMs"];
             delete resolveOut["shaPollIntervalMs"];
             shaPollChanged = true;
         }
         if ("shaPollMaxAttempts" in resolve) {
             process.stderr.write(`pr-shepherd: config key "resolve.shaPollMaxAttempts" moved to "resolve.shaPoll.maxAttempts".\n`);
-            shaPollOut["maxAttempts"] = resolve["shaPollMaxAttempts"];
+            shaPollOut["maxAttempts"] =
+                resolve["shaPoll"]?.["maxAttempts"] ??
+                    resolve["shaPollMaxAttempts"];
             delete resolveOut["shaPollMaxAttempts"];
             shaPollChanged = true;
         }
@@ -112,17 +116,17 @@ function applyCompat(raw) {
         const checksOut = { ...checks };
         if ("relevantEvents" in checks) {
             process.stderr.write(`pr-shepherd: config key "checks.relevantEvents" renamed to "checks.ciTriggerEvents".\n`);
-            checksOut["ciTriggerEvents"] = checks["relevantEvents"];
+            checksOut["ciTriggerEvents"] = checksOut["ciTriggerEvents"] ?? checks["relevantEvents"];
             delete checksOut["relevantEvents"];
         }
         if ("logLinesKept" in checks) {
             process.stderr.write(`pr-shepherd: config key "checks.logLinesKept" renamed to "checks.logMaxLines".\n`);
-            checksOut["logMaxLines"] = checks["logLinesKept"];
+            checksOut["logMaxLines"] = checksOut["logMaxLines"] ?? checks["logLinesKept"];
             delete checksOut["logLinesKept"];
         }
         if ("logExcerptMaxChars" in checks) {
             process.stderr.write(`pr-shepherd: config key "checks.logExcerptMaxChars" renamed to "checks.logMaxChars".\n`);
-            checksOut["logMaxChars"] = checks["logExcerptMaxChars"];
+            checksOut["logMaxChars"] = checksOut["logMaxChars"] ?? checks["logExcerptMaxChars"];
             delete checksOut["logExcerptMaxChars"];
         }
         out["checks"] = checksOut;

package/{dist → bin}/github/client.mjs

@@ -89,7 +89,6 @@ export async function getCurrentPrNumber() {
     }
 }
 async function getCurrentBranch() {
-    await runGh(["--version"]); // warm up gh CLI before git call
     // Use git directly for branch name — gh doesn't expose it.
     const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
     return stdout.trim();

package/bin/pr-shepherd

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("./index.mjs")

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "pr-shepherd",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",
   "type": "module",
   "bin": {
-    "pr-shepherd": "./dist/index.mjs"
+    "pr-shepherd": "bin/index.mjs"
   },
   "files": [
-    "dist/**",
+    "bin/**",
     "skills/**",
     ".claude-plugin/**",
     "marketplace.json",
@@ -17,21 +17,21 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=22.0.0"
   },
   "dependencies": {
     "yaml": "^2.7.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "oxfmt": "latest",
-    "oxlint": "latest",
+    "oxfmt": "^0.45.0",
+    "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4",
     "@vitest/coverage-v8": "^4.1.4"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/config.json dist/ && mkdir -p dist/github && cp -r src/github/gql dist/github/",
+    "build": "node scripts/build.mjs",
     "prepare": "npm run build",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "typecheck": "tsc --noEmit",

package/skills/check/SKILL.md

@@ -40,24 +40,22 @@ Parse the JSON output and report all three:
 
 ## Rebase policy
 
-```bash
-BASE_BRANCH=$(gh pr view <N> --json baseRefName --jq '.baseRefName')
-```
+The CLI already determines whether a rebase is warranted. Read `report.mergeStatus.status` directly:
 
-Rebase (`git fetch origin && git rebase origin/<BASE_BRANCH> && git push --force-with-lease`) when:
+- `CONFLICTS` — a rebase is required to resolve the merge conflict before the PR can land.
+- `BEHIND` — a rebase may be appropriate; a `flaky` failure while `BEHIND` is the canonical rebase signal. If all checks pass but the PR is `BEHIND`, a rebase is optional.
+- Any other status — no rebase needed.
 
-- Merge conflicts with main (`report.mergeStatus.status == 'CONFLICTS'`), OR
-- About to push commits and branch is behind main, OR
-- `failureKind == 'flaky'` AND branch is behind main
-
-Do NOT rebase when nothing to push, no conflicts, and no flaky failures.
+Do not re-derive these conditions from raw branch state. For automated monitoring that acts on these signals, use `/pr-shepherd:monitor` — it handles rebase decisions end-to-end.
 
 ## CI budget policy
 
-- **actionable**: Summarize errors. Fix in next step.
-- **infrastructure**: Re-run: `gh run rerun <runId> --failed`
-- **timeout**: Re-run: `gh run rerun <runId> --failed`
-- **flaky**: Do NOT cancel. Rebase if behind main.
+Each entry in `report.checks` carries a `failureKind` field. Read it directly rather than re-classifying failures:
+
+- `actionable` — the failure is code-level and needs a fix.
+- `infrastructure` — transient infra problem; re-run with `gh run rerun <runId> --failed`.
+- `timeout` — job exceeded the time limit; re-run with `gh run rerun <runId> --failed`.
+- `flaky` — known-flaky test; do NOT cancel. Rebase first if `mergeStatus.status` is `BEHIND`.
 
 ## Never declare ready to merge
 

package/skills/monitor/SKILL.md

@@ -79,7 +79,7 @@ Parse the `action` field and act:
   1. For each item in `fix.threads` and `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 13` after addressing it. Do not attempt to fix these automatically.
+     - 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)