pr-shepherd 0.55.0 → 0.55.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.55.0",
+  "version": "0.55.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/cli/iterate-formatter.mjs

@@ -181,4 +181,7 @@ function appendUnreportedLines(lines, result) {
     if (result.trunkBehindBy !== undefined && result.trunkBehindBy > 0) {
         lines.push(`**trunk behind** \`${result.trunkBehindBy}\``);
     }
+    if (result.baseBehindBy !== undefined && result.baseBehindBy > 0) {
+        lines.push(`**behind** \`${result.baseBehindBy}\``);
+    }
 }

package/bin/cli/iterate-lean.mjs

@@ -72,6 +72,8 @@ export function projectIterateLean(result, opts) {
         }),
         ...(result.trunkBehindBy !== undefined &&
             result.trunkBehindBy > 0 && { trunkBehindBy: result.trunkBehindBy }),
+        ...(result.baseBehindBy !== undefined &&
+            result.baseBehindBy > 0 && { baseBehindBy: result.baseBehindBy }),
         ...(result.quotaWarning && { quotaWarning: result.quotaWarning }),
         ...(result.ruleAutoResolve && {
             ruleAutoResolve: projectRuleAutoResolve(result.ruleAutoResolve),

package/bin/commands/check-unreported.d.mts

@@ -4,6 +4,8 @@ import type { RepoInfo } from "../github/client.mts";
 export interface UnreportedRequiredFields {
     unreportedRequiredChecks?: string[];
     trunkBehindBy?: number;
+    /** Commits on the PR base that this head does not contain. Omitted when zero or a stack. */
+    baseBehindBy?: number;
     actionsWorkflowInProgress?: true;
     stackBottomPr?: number;
     headRefName: string;

package/bin/commands/check-unreported.mjs

@@ -1,5 +1,5 @@
 import { actionsWorkflowInProgress, reportedCheckNames, unreportedRequiredContexts, } from "../checks/unreported-required.mjs";
-import { loadMergeTargetStatus } from "../github/merge-target-rules.mjs";
+import { loadBaseBehindBy, loadMergeTargetStatus } from "../github/merge-target-rules.mjs";
 /** Load trunk rules for a stack and diff them against the head's check names. */
 export async function collectUnreportedRequired(input) {
     const localContexts = input.batchData.branchRules?.requiredStatusCheckContexts ??
@@ -16,10 +16,14 @@ export async function collectUnreportedRequired(input) {
     });
     const unreported = unreportedRequiredContexts(target.contexts, reportedCheckNames(input.checks));
     const actionsRunning = actionsWorkflowInProgress(input.suites, new Set(input.relevantEvents));
+    const baseBehindBy = unreported.length > 0 && !input.batchData.stack
+        ? await loadBaseBehindBy(input.owner, input.name, input.batchData.baseRefName, input.batchData.headRefOid)
+        : 0;
     return {
         ...(unreported.length > 0 && { unreportedRequiredChecks: unreported }),
         ...(target.trunkBehindBy !== undefined &&
             target.trunkBehindBy > 0 && { trunkBehindBy: target.trunkBehindBy }),
+        ...(baseBehindBy > 0 && { baseBehindBy }),
         ...(actionsRunning && { actionsWorkflowInProgress: true }),
         ...(target.stackBottomPr !== undefined && { stackBottomPr: target.stackBottomPr }),
         headRefName: input.batchData.headRefName,
@@ -32,8 +36,10 @@ export async function collectUnreportedRequired(input) {
  */
 export async function refreshCachedUnreported(report, repo) {
     const stack = report.mergeStatus?.mergeRequirements?.stack;
-    if (!stack || !report.headRefName)
+    if (!report.headRefName)
         return report;
+    if (!stack)
+        return refreshBaseBehind(report, repo);
     const target = await loadMergeTargetStatus({
         owner: repo.owner,
         name: repo.name,
@@ -60,6 +66,28 @@ export async function refreshCachedUnreported(report, repo) {
         next.status = "PENDING";
     return next;
 }
+/** A fingerprint hit can keep a stale base compare after main moves. */
+async function refreshBaseBehind(report, repo) {
+    if ((report.unreportedRequiredChecks?.length ?? 0) === 0) {
+        if (report.baseBehindBy === undefined)
+            return report;
+        const cleared = { ...report };
+        delete cleared.baseBehindBy;
+        return cleared;
+    }
+    // A missing head OID must not fall back to the branch name. That name can
+    // resolve inside the base repository when the PR comes from a fork.
+    const headOid = report.headSha;
+    if (!headOid)
+        return report;
+    const behind = await loadBaseBehindBy(repo.owner, repo.name, report.baseBranch, headOid);
+    const next = { ...report };
+    if (behind > 0)
+        next.baseBehindBy = behind;
+    else
+        delete next.baseBehindBy;
+    return next;
+}
 function reportChecks(report) {
     return [
         ...report.checks.passing,

package/bin/commands/check.mjs

@@ -347,6 +347,7 @@ export async function runCheck(opts) {
             unreportedRequiredChecks: unreported.unreportedRequiredChecks,
         }),
         ...(unreported.trunkBehindBy !== undefined && { trunkBehindBy: unreported.trunkBehindBy }),
+        ...(unreported.baseBehindBy !== undefined && { baseBehindBy: unreported.baseBehindBy }),
         ...(unreported.actionsWorkflowInProgress && {
             actionsWorkflowInProgress: true,
         }),

package/bin/commands/commit-suggestion-instruction.d.mts

@@ -3,7 +3,7 @@
  * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
  * only the trigger and the concrete command; refusal/drift handling is invariant across
  * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook
- * instead of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts
+ * instead of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts
  * minimal").
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   e.g. `"## Review threads"`.

package/bin/commands/commit-suggestion-instruction.mjs

@@ -4,7 +4,7 @@ import { buildPrShepherdCommand } from "../cli/runner.mjs";
  * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
  * only the trigger and the concrete command; refusal/drift handling is invariant across
  * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook
- * instead of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts
+ * instead of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts
  * minimal").
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   e.g. `"## Review threads"`.

package/bin/commands/iterate/base.mjs

@@ -29,6 +29,8 @@ export function buildIterateBase(report, readyState) {
         }),
         ...(report.trunkBehindBy !== undefined &&
             report.trunkBehindBy > 0 && { trunkBehindBy: report.trunkBehindBy }),
+        ...(report.baseBehindBy !== undefined &&
+            report.baseBehindBy > 0 && { baseBehindBy: report.baseBehindBy }),
         ...(report.fingerprintReused === true && { fingerprintReused: true }),
         ...(ruleAutoResolve && { ruleAutoResolve }),
     };

package/bin/commands/iterate/check-instructions.d.mts

@@ -4,7 +4,7 @@ export declare function buildCrStaleClause(reviews: Review[]): string;
 /**
  * Build the optional behind-base push hint. Empty unless the branch is actually behind its base
  * and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
- * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in CLAUDE.md); this
+ * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in AGENTS.md); this
  * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
  * point of use (rather than at config load) so a malformed rc file value (non-string, or
  * whitespace-only) degrades to "no hint" instead of rendering garbage into agent-facing text or

package/bin/commands/iterate/check-instructions.mjs

@@ -8,7 +8,7 @@ export function buildCrStaleClause(reviews) {
 /**
  * Build the optional behind-base push hint. Empty unless the branch is actually behind its base
  * and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
- * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in CLAUDE.md); this
+ * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in AGENTS.md); this
  * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
  * point of use (rather than at config load) so a malformed rc file value (non-string, or
  * whitespace-only) degrades to "no hint" instead of rendering garbage into agent-facing text or

package/bin/commands/iterate/escalate.mjs

@@ -242,7 +242,7 @@ export function buildEscalateSuggestion(triggers, detail) {
     }
     if (triggers.includes("required-checks-unreported")) {
         const names = detail ? ` (${detail})` : "";
-        return `Required checks are still unreported after one close/reopen of this head${names}. Another reopen will not create a job the workflow does not emit. Path filters are the usual cause.`;
+        return `Required checks are still unreported${names}, and no CI is running. Rebase and push is the fix when the branch is behind. This head is current, and another reopen will not create a job the workflow does not emit. Path filters are the usual cause. Investigate that, then handle the missing checks manually.`;
     }
     if (triggers.includes("stall-state-unavailable")) {
         const reason = detail ?? "unknown error";

package/bin/commands/iterate/unreported-required.mjs

@@ -12,23 +12,35 @@ function decideUnreportedRequired(input) {
         return input.otherAutonomousWork ? "none" : "escalate";
     return "reopen";
 }
-function buildUnreportedRequiredInstruction(input) {
-    const listed = input.names.map((name) => `\`${name}\``).join(", ");
-    const observed = input.trunkBehindBy !== undefined && input.trunkBehindBy > 0
-        ? `The stack trunk compare is behind by ${input.trunkBehindBy}.`
-        : input.behind
-            ? "This PR's derived merge status is BEHIND."
-            : "The stack trunk compare is not behind and this PR's derived merge status is not BEHIND.";
-    const update = input.stackRebase
+function listedChecks(names) {
+    return names.map((name) => `\`${name}\``).join(", ");
+}
+/** Facts, then rebase-and-push, then investigate or escalate if that push does not start CI. */
+function buildUnreportedRequiredInstructions(input) {
+    const names = listedChecks(input.names);
+    const gap = input.behindBy > 0 && input.trunk
+        ? `The stack trunk is behind by ${input.behindBy} commits.`
+        : input.behindBy > 0
+            ? `This branch is behind \`${input.baseBranch}\` by ${input.behindBy} commits.`
+            : input.behind
+                ? "This PR's derived merge status is BEHIND."
+                : `This branch is not behind \`${input.baseBranch}\`.`;
+    const facts = `${gap} No CI checks are running, and required checks have not passed: ${names}.`;
+    if (!input.behind) {
+        return [
+            facts,
+            `Retrigger workflows once for this head with \`gh pr close ${input.pr} -R ${input.repo}\` then \`gh pr reopen ${input.pr} -R ${input.repo}\`.`,
+            "If those checks are still missing on the next poll, investigate why the workflows did not start. Do not close the PR again. Shepherd escalates with `required-checks-unreported` when this remains the only blocker.",
+        ];
+    }
+    const rebase = input.stackRebase
         ? `${input.stackRebase} Then push the rewritten stack with \`gh stack push\`.`
-        : `Rebase or otherwise update the PR branch from \`${input.baseBranch}\` according to repository conventions, then push.`;
+        : `Rebase onto \`${input.baseBranch}\` and push.`;
     return [
-        `Required status checks have no check run and no status context on this head, and no Actions workflow is running: ${listed}.`,
-        observed,
-        `If the stack trunk is behind or this PR is behind its base, update the branch so a pull_request synchronize event runs: ${update}`,
-        `Otherwise retrigger workflows once for this head with \`gh pr close ${input.pr} -R ${input.repo}\` then \`gh pr reopen ${input.pr} -R ${input.repo}\`.`,
-        "Do not close the PR again if those checks are still missing on the next poll.",
-    ].join(" ");
+        facts,
+        `${rebase} Rebase and push is how these checks start.`,
+        "If that push does not start the checks, investigate why the workflows did not run. Shepherd escalates with `required-checks-unreported` when the branch is current and this remains the only blocker.",
+    ];
 }
 export async function planUnreportedRequired(input) {
     const names = input.report.unreportedRequiredChecks ?? [];
@@ -38,7 +50,8 @@ export async function planUnreportedRequired(input) {
     const inQueue = input.report.mergeQueue?.inQueue === true;
     if (names.length === 0 || actionsRunning || failing || conflicts || inQueue)
         return {};
-    const behind = (input.report.trunkBehindBy ?? 0) > 0 || input.report.mergeStatus.status === "BEHIND";
+    const behindBy = input.report.trunkBehindBy ?? input.report.baseBehindBy ?? 0;
+    const behind = behindBy > 0 || input.report.mergeStatus.status === "BEHIND";
     const decision = decideUnreportedRequired({
         behind,
         alreadyRetriggered: sameCiRetrigger(await readCiRetrigger(input.stateKey), input.headSha, names),
@@ -49,19 +62,20 @@ export async function planUnreportedRequired(input) {
     if (decision === "escalate")
         return { escalate: escalateUnreported(input.base, input.report, names) };
     const rebase = stackRebase(input.report);
-    const instruction = buildUnreportedRequiredInstruction({
+    const instructions = buildUnreportedRequiredInstructions({
         names,
         repo: input.report.repo,
         pr: input.report.pr,
         baseBranch: input.report.baseBranch,
         behind,
-        ...(input.report.trunkBehindBy !== undefined && { trunkBehindBy: input.report.trunkBehindBy }),
+        behindBy,
+        trunk: (input.report.trunkBehindBy ?? 0) > 0,
         ...(rebase && { stackRebase: rebase }),
     });
     if (decision === "reopen") {
         await writeCiRetrigger(input.stateKey, { headSha: input.headSha, contexts: names });
     }
-    return { repairInstructions: [instruction] };
+    return { repairInstructions: instructions };
 }
 export function buildUnreportedFixResult(base, report, instructions) {
     const prUrl = formatPrUrl(report.repo, report.pr);

package/bin/commands/shepherd-journal.d.mts

@@ -9,6 +9,6 @@ export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body un
  * Build the Shepherd Journal instruction step. The reference-citation convention (link
  * threads/comments from their headings, cite reviews by ID) is invariant across every
  * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
- * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
+ * of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts minimal").
  */
 export declare function buildShepherdJournalInstruction(prReference: string | number): string;

package/bin/commands/shepherd-journal.mjs

@@ -10,7 +10,7 @@ export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `##
  * Build the Shepherd Journal instruction step. The reference-citation convention (link
  * threads/comments from their headings, cite reviews by ID) is invariant across every
  * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
- * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
+ * of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts minimal").
  */
 export function buildShepherdJournalInstruction(prReference) {
     // Single-quote the placeholder so a substituted decision stays literal in the shell.

package/bin/github/gql/base-behind.gql

@@ -0,0 +1,20 @@
+# Commits on the PR base that the head branch does not contain.
+# Fetched only when required checks never reported, so a BLOCKED merge state
+# cannot hide a behind base.
+query BaseBehind($owner: String!, $repo: String!, $qualifiedName: String!, $headRef: String!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  repository(owner: $owner, name: $repo) {
+    ref(qualifiedName: $qualifiedName) {
+      compare(headRef: $headRef) {
+        behindBy
+      }
+    }
+  }
+}

package/bin/github/merge-target-rules.d.mts

@@ -18,3 +18,11 @@ export declare function loadMergeTargetStatus(input: {
         baseRefName: string;
     } | null;
 }): Promise<MergeTargetStatus>;
+/**
+ * Commits on the PR base that `headRef` does not contain.
+ * Pass the head commit OID. A fork's branch name can exist on the base
+ * repository, or fail to resolve, and either result hides a real behind count.
+ * `mergeStateStatus` stays `BLOCKED` when a conversation or an expected check
+ * is also open, so this compare is the behind count that status hides.
+ */
+export declare function loadBaseBehindBy(owner: string, name: string, baseRefName: string, headRef: string): Promise<number>;

package/bin/github/merge-target-rules.mjs

@@ -2,7 +2,7 @@ import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { parseBranchRules } from "./batch-parsers-rules.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { missingRepositoryError } from "./errors.mjs";
-import { REF_RULES_QUERY } from "./queries.mjs";
+import { BASE_BEHIND_QUERY, REF_RULES_QUERY } from "./queries.mjs";
 import { readStackTopology } from "./stack-read.mjs";
 /**
  * Required status contexts for the branch GitHub actually merges into.
@@ -34,6 +34,29 @@ async function bottomOpenLayer(pr, repo, trunk) {
     }
     return bottom;
 }
+/**
+ * Commits on the PR base that `headRef` does not contain.
+ * Pass the head commit OID. A fork's branch name can exist on the base
+ * repository, or fail to resolve, and either result hides a real behind count.
+ * `mergeStateStatus` stays `BLOCKED` when a conversation or an expected check
+ * is also open, so this compare is the behind count that status hides.
+ */
+export async function loadBaseBehindBy(owner, name, baseRefName, headRef) {
+    const qualifiedName = `refs/heads/${baseRefName}`;
+    const { data } = await graphqlWithRateLimit(BASE_BEHIND_QUERY, {
+        owner,
+        repo: name,
+        qualifiedName,
+        headRef,
+    });
+    if (!data.repository)
+        throw missingRepositoryError({ owner, name });
+    const ref = data.repository.ref;
+    if (!ref) {
+        throw new ShepherdError(`Branch ${qualifiedName} was not found in ${owner}/${name}`, EXIT.TEMPFAIL);
+    }
+    return ref.compare?.behindBy ?? 0;
+}
 async function fetchRefRules(owner, name, qualifiedName, headRef) {
     const { data } = await graphqlWithRateLimit(REF_RULES_QUERY, {
         owner,

package/bin/github/queries.d.mts

@@ -16,6 +16,8 @@ export declare const PR_FINGERPRINT_QUERY: string;
 export declare const POLL_SUMMARY_FRAGMENT: string;
 /** Trunk branch rules plus how far `headRef` is behind that branch. */
 export declare const REF_RULES_QUERY: string;
+/** How far a non-stack head is behind its PR base. One compare, no rules payload. */
+export declare const BASE_BEHIND_QUERY: string;
 /**
  * Pages older status contexts for one commit with the same node selection as
  * the compact summary, so hydrated and first-page nodes fingerprint alike.

package/bin/github/queries.mjs

@@ -21,6 +21,8 @@ const POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT = gql("poll-summary-check-contexts.gq
 export const POLL_SUMMARY_FRAGMENT = `${gql("ref-rules.gql")}\n${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}`;
 /** Trunk branch rules plus how far `headRef` is behind that branch. */
 export const REF_RULES_QUERY = `${gql("ref-rules.gql")}\n${gql("ref-rules-query.gql")}`;
+/** How far a non-stack head is behind its PR base. One compare, no rules payload. */
+export const BASE_BEHIND_QUERY = gql("base-behind.gql");
 /**
  * Pages older status contexts for one commit with the same node selection as
  * the compact summary, so hydrated and first-page nodes fingerprint alike.

package/bin/types/iterate.d.mts

@@ -49,6 +49,8 @@ export interface IterateResultBase {
     unreportedRequiredChecks?: string[];
     /** Commits on the stack trunk that the bottom open layer does not contain. Omitted when zero. */
     trunkBehindBy?: number;
+    /** Commits on the PR base that this head does not contain. Omitted when zero. */
+    baseBehindBy?: number;
     activity?: PrActivitySummary;
     mergeQueue?: import("./merge-queue.mts").MergeQueueReport;
     apiUsage?: ApiUsage;

package/bin/types/report.d.mts

@@ -110,6 +110,8 @@ export interface ShepherdReport {
     unreportedRequiredChecks?: string[];
     /** Commits on the stack trunk that the bottom open layer does not contain. Omitted when zero. */
     trunkBehindBy?: number;
+    /** Commits on the PR base that this head does not contain. Omitted when zero. */
+    baseBehindBy?: number;
     /** A relevant Actions workflow suite on the head has not completed. */
     actionsWorkflowInProgress?: true;
     /** Bottom open layer of this PR's native stack. Starts a trunk rebase. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.55.0",
+  "version": "0.55.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.55.0",
+  "version": "0.55.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.55.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.55.1", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.55.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.55.1", "pr-shepherd-mcp"]
   }
 }

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

@@ -18,7 +18,7 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
 
 ## Arguments: $ARGUMENTS
 
-1. Parse optional PR numbers, repository-qualified `owner/repo#N` references, or GitHub PR URLs and an optional `--merge` flag from `$ARGUMENTS`; alternatively parse one `--stack PR` selector. A clear request to merge, land, or enqueue the selected PR or stack also opts into `--merge` without a literal flag; a request only to create or open a PR does not. When the user asks to shepherd or merge a native stack and supplies an anchor PR without a literal `--stack`, use that PR as the `--stack` selector. Otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
+1. Parse optional PR numbers, repository-qualified `owner/repo#N` references, or GitHub PR URLs and an optional `--merge` flag from `$ARGUMENTS`; alternatively parse one `--stack PR` selector. A clear request to merge, land, or enqueue the selected PR or stack also opts into `--merge` without a literal flag; a request only to create or open a PR does not. When the user asks to shepherd or merge a native stack and supplies an anchor PR without a literal `--stack`, use that PR as the `--stack` selector. Otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` standards while making changes.
 
 2. For the CLI, convert supplied `owner/repo#N` references to `https://github.com/owner/repo/pull/N`; otherwise pass supplied URLs or bare numbers unchanged, then run `pr-shepherd [PR ...] --until-terminal`, or `pr-shepherd --stack PR --until-terminal` for a stack, omitting `[PR ...]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; aggregate selectors return their next stack action or terminal result. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first repository-qualify every supplied reference with its GitHub URL or `owner/repo#N`; resolve bare numbers through `gh pr view <number> --json url --jq .url`, and resolve an omitted target with `gh pr view --json url --jq .url`. If that does not produce the required qualified selector, stop and report that MCP cannot safely determine it. Otherwise call `iterate` with `pr`, `prs`, or `stack` as selected, plus `merge: true` when merge intent was requested, and print its full result.