pr-shepherd 0.55.2 → 0.56.0

package/bin/github/reply-thread-transcripts.mjs

@@ -0,0 +1,89 @@
+import { graphqlWithRateLimit } from "./client.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { rateLimitKind } from "./rate-limit-kind.mjs";
+import { REPLY_THREAD_COMMENTS_QUERY, REPLY_THREAD_TRANSCRIPTS_QUERY } from "./queries.mjs";
+import { threadTranscriptBodies } from "../threads/transcript.mjs";
+import { mapPool } from "../util/pool.mjs";
+const IDS_PER_REQUEST = 20;
+const CONCURRENCY = 4;
+const MAX_COMMENT_PAGES = 100;
+/** Best-effort transcript evidence; it never filters user-supplied mutation IDs. */
+export async function fetchReplyThreadTranscripts(pr, repo, requestedIds) {
+    const ids = [...new Set(requestedIds)];
+    if (ids.length === 0)
+        return new Map();
+    const expectedRepo = `${repo.owner}/${repo.name}`.toLowerCase();
+    const requested = new Set(ids);
+    const chunks = [];
+    for (let offset = 0; offset < ids.length; offset += IDS_PER_REQUEST) {
+        chunks.push(ids.slice(offset, offset + IDS_PER_REQUEST));
+    }
+    let stopped = false;
+    const firstPages = await mapPool(chunks, CONCURRENCY, async (chunk) => {
+        if (stopped)
+            return [];
+        try {
+            const result = await graphqlWithRateLimit(REPLY_THREAD_TRANSCRIPTS_QUERY, {
+                ids: chunk,
+            });
+            if (result.rateLimit?.remaining === 0)
+                stopped = true;
+            return result.data.nodes.filter((node) => node?.__typename === "PullRequestReviewThread" &&
+                node.id !== undefined &&
+                requested.has(node.id) &&
+                node.pullRequest?.number === pr &&
+                node.pullRequest.repository.nameWithOwner.toLowerCase() === expectedRepo &&
+                node.comments !== undefined);
+        }
+        catch (error) {
+            if (isThrottle(error))
+                stopped = true;
+            return [];
+        }
+    });
+    const threads = firstPages.flat();
+    const completed = await mapPool(threads, CONCURRENCY, async (thread) => {
+        try {
+            return await completeThread(thread, () => stopped, () => {
+                stopped = true;
+            });
+        }
+        catch (error) {
+            if (isThrottle(error))
+                stopped = true;
+            return null;
+        }
+    });
+    return new Map(completed.filter((entry) => entry !== null));
+}
+async function completeThread(thread, isStopped, stop) {
+    if (!thread.id || !thread.comments)
+        return null;
+    const bodies = thread.comments.nodes.map((comment) => comment.body);
+    let page = thread.comments;
+    const seenCursors = new Set();
+    let pages = 1;
+    while (page.pageInfo.hasNextPage) {
+        const cursor = page.pageInfo.endCursor;
+        if (!cursor || seenCursors.has(cursor) || pages >= MAX_COMMENT_PAGES || isStopped())
+            return null;
+        seenCursors.add(cursor);
+        const result = await graphqlWithRateLimit(REPLY_THREAD_COMMENTS_QUERY, {
+            id: thread.id,
+            cursor,
+        });
+        if (result.rateLimit?.remaining === 0)
+            stop();
+        const next = result.data.node;
+        if (next?.__typename !== "PullRequestReviewThread" || next.id !== thread.id || !next.comments) {
+            return null;
+        }
+        page = next.comments;
+        bodies.push(...page.nodes.map((comment) => comment.body));
+        pages += 1;
+    }
+    return bodies.length > 0 ? [thread.id, threadTranscriptBodies(bodies)] : null;
+}
+function isThrottle(error) {
+    return error instanceof GitHubRequestError && rateLimitKind(error) !== null;
+}

package/bin/github/rest-http.mjs

@@ -98,6 +98,7 @@ export async function restWithRateLimit(method, path, body, opts) {
             rateLimit,
             retryAfterSeconds,
             authSource,
+            responseMessage: sanitizeBody(text),
         });
     }
     if (ct.includes("application/json")) {

package/bin/github/rest-text.d.mts

@@ -1 +1,2 @@
-export declare function restText(path: string): Promise<string>;
+import { type RateLimitInfo } from "./http-utils.mts";
+export declare function restText(path: string, onRateLimit?: (rateLimit?: RateLimitInfo) => void): Promise<string>;

package/bin/github/rest-text.mjs

@@ -3,11 +3,11 @@ import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
-import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody } from "./http-utils.mjs";
+import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody, } from "./http-utils.mjs";
 import { recordApiTelemetry } from "./api-telemetry.mjs";
 import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
-export async function restText(path) {
+export async function restText(path, onRateLimit) {
     const url = `${BASE_URL}${path}`;
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
@@ -28,6 +28,7 @@ export async function restText(path) {
     }));
     const durationMs = Math.round(performance.now() - retryT0);
     const rateLimit = parseRateLimit(res.headers) ?? undefined;
+    onRateLimit?.(rateLimit);
     const retryAfterSeconds = parseRetryAfter(res.headers);
     recordApiTelemetry({ kind: "REST", method: "GET", authSource, rateLimit });
     if ([301, 302, 307, 308].includes(res.status)) {
@@ -62,6 +63,7 @@ export async function restText(path) {
             rateLimit,
             retryAfterSeconds,
             authSource,
+            responseMessage: sanitizeBody(text),
         });
     }
     appendEntry(formatResponseEntry({
@@ -114,6 +116,7 @@ async function followRestTextRedirect(res, entry) {
             status: redirectRes.status,
             rateLimit: parseRateLimit(redirectRes.headers) ?? undefined,
             retryAfterSeconds: parseRetryAfter(redirectRes.headers),
+            responseMessage: "",
         });
     }
     return redirectRes.text();

package/bin/github/thread-comments.d.mts

@@ -1,2 +1,6 @@
+import { type RateLimitInfo } from "./client.mts";
 import type { RawThread } from "./batch-raw-types.mts";
-export declare function hydrateThreadCommentPages(threads: RawThread[]): Promise<RawThread[]>;
+export declare function hydrateThreadCommentPages(threads: RawThread[], initialRateLimit?: RateLimitInfo): Promise<{
+    threads: RawThread[];
+    rateLimit?: RateLimitInfo;
+}>;

package/bin/github/thread-comments.mjs

@@ -4,23 +4,47 @@ import { paginateForward } from "./pagination.mjs";
 import { REVIEW_THREAD_COMMENTS_QUERY } from "./queries.mjs";
 import { mapPool } from "../util/pool.mjs";
 const THREAD_COMMENT_PAGE_CONCURRENCY = 4;
-export async function hydrateThreadCommentPages(threads) {
-    const gate = {};
-    return mapPool(threads, THREAD_COMMENT_PAGE_CONCURRENCY, (thread) => hydrateThreadCommentPage(thread, gate));
+export async function hydrateThreadCommentPages(threads, initialRateLimit) {
+    const gate = {
+        rateLimit: initialRateLimit,
+        exhausted: initialRateLimit?.remaining === 0,
+    };
+    const hydrated = await mapPool(threads, THREAD_COMMENT_PAGE_CONCURRENCY, async (thread) => {
+        if (gate.error !== undefined)
+            return thread;
+        try {
+            return await hydrateThreadCommentPage(thread, gate);
+        }
+        catch (error) {
+            gate.error ??= error;
+            return thread;
+        }
+    });
+    if (gate.error !== undefined)
+        throw gate.error;
+    return { threads: hydrated, rateLimit: gate.rateLimit };
 }
 async function hydrateThreadCommentPage(thread, gate) {
     const pageInfo = thread.comments.pageInfo;
     if (!pageInfo?.hasNextPage || !pageInfo.endCursor)
         return thread;
     const extra = await paginateForward(async (cursor) => {
-        if (gate.remaining === 0) {
-            throw new GitHubRequestError("GitHub GraphQL rate limit remaining is 0; thread comment pagination incomplete", { status: 403 });
+        if (gate.error !== undefined)
+            throw gate.error;
+        if (gate.exhausted) {
+            throw new GitHubRequestError("GitHub GraphQL rate limit remaining is 0; thread comment pagination incomplete", { status: 403, rateLimit: gate.rateLimit });
         }
         const res = await graphqlWithRateLimit(REVIEW_THREAD_COMMENTS_QUERY, {
             threadId: thread.id,
             ...(cursor ? { commentsCursor: cursor } : {}),
         });
-        gate.remaining = res.rateLimit?.remaining;
+        if (res.rateLimit?.remaining === 0) {
+            gate.rateLimit = res.rateLimit;
+            gate.exhausted = true;
+        }
+        else if (!gate.exhausted) {
+            gate.rateLimit = res.rateLimit ?? gate.rateLimit;
+        }
         const node = res.data.node;
         if (!node?.comments) {
             const nodeType = node?.__typename ?? "null";

package/bin/mcp/server.mjs

@@ -10,6 +10,7 @@ import { formatPollSummaryResult } from "../cli/poll-summary-formatter.mjs";
 import { projectStackOverview } from "../cli/stack-overview.mjs";
 import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
+import { extractShepherdJournal } from "../journal/index.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
 const pr = z
     .string()
@@ -87,7 +88,8 @@ const suggestionPatchesInputSchema = z.object({
 });
 /** Creates a local-only MCP server with Shepherd's public operations. */
 export function createPrShepherdMcpServer(options = {}) {
-    const shepherd = options.shepherd ?? createPrShepherd({ cwd: options.cwd });
+    let shepherd = options.shepherd;
+    const getShepherd = () => (shepherd ??= createPrShepherd({ cwd: options.cwd }));
     const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
     server.registerTool("iterate", {
         description: "Inspect one pull request, an explicit same-repository set, or a native stack and return one Shepherd tick.",
@@ -103,7 +105,7 @@ export function createPrShepherdMcpServer(options = {}) {
         const opts = {
             readyDelaySuffix: input.readyDelaySeconds === undefined ? undefined : `${input.readyDelaySeconds}s`,
         };
-        return runTool(() => runIterateSelector(shepherd, requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
+        return runTool(() => runIterateSelector(getShepherd(), requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
             ? formatPollSummaryResult(result)
             : formatIterateResult(result, opts), (result) => isPollSummary(result)
             ? result.selection.kind === "stack"
@@ -120,7 +122,32 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.apply(requireRepositoryQualifiedPr(input)), formatApplyResult));
+    }, async (input) => runTool(() => getShepherd().apply(requireRepositoryQualifiedPr(input)), formatApplyResult));
+    server.registerTool("extract_journal", {
+        description: "Extract the validated Shepherd Journal from a supplied Markdown body without I/O.",
+        inputSchema: z.object({ body: z.string() }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (input) => runTool(async () => {
+        if (typeof input.body !== "string") {
+            throw new PrShepherdValidationError("body must be a Markdown string");
+        }
+        return extractShepherdJournal(input.body);
+    }, JSON.stringify));
+    server.registerTool("get_journal", {
+        description: "Fetch one pull request body with GraphQL and extract its Shepherd Journal.",
+        inputSchema: z.object({ pr }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => getShepherd().getJournal(requireRepositoryQualifiedPr(input)), JSON.stringify));
     server.registerTool("build_suggestion_patches", {
         description: "Build, but never apply, an ordered list of eligible review suggestion patches.",
         inputSchema: suggestionPatchesInputSchema,
@@ -130,7 +157,7 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.buildSuggestionPatches(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
+    }, async (input) => runTool(() => getShepherd().buildSuggestionPatches(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
     server.registerTool("build_suggestion_patch", {
         description: "Deprecated: use build_suggestion_patches with a one-item suggestions array.",
         inputSchema: suggestionPatchInputSchema,
@@ -140,7 +167,7 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.buildSuggestionPatch(requireRepositoryQualifiedPr(input)), formatCommitSuggestionResult));
+    }, async (input) => runTool(() => getShepherd().buildSuggestionPatch(requireRepositoryQualifiedPr(input)), formatCommitSuggestionResult));
     return server;
 }
 function runIterateSelector(shepherd, input) {

package/bin/quota-warning.mjs

@@ -5,8 +5,8 @@ export function buildQuotaAwareContinuation(warning, prefix) {
     const opening = warning.resource === "combined"
         ? "GitHub's GraphQL and REST core quotas are both low. Keep using pr-shepherd at the cadence below. Do not shift incidental calls between GraphQL and REST."
         : warning.resource === "core"
-            ? `GitHub's REST core quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below. Do not add incidental REST \`gh\` calls (\`gh pr view\`, \`gh pr review\`, \`gh api\`) while REST core is below its warning threshold.`
-            : `GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool.`;
+            ? `GitHub's REST core quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below. Do not add incidental REST \`gh api repos/OWNER/REPO/pulls/PR\` calls while REST core is below its warning threshold.`
+            : `GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR reads that do not need Shepherd's full snapshot, use explicit REST endpoints such as \`gh api repos/OWNER/REPO/pulls/PR\` — they draw on the separate REST budget, not the depleted GraphQL pool.`;
     const resetLabel = warning.resource === "combined"
         ? "both quotas have reset"
         : warning.resource === "core"

package/bin/reporters/agent.mjs

@@ -66,6 +66,7 @@ export function toAgentCheck(c) {
         ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
         ...(c.summary !== undefined && { summary: c.summary }),
         ...(c.logExcerpt !== undefined && { logExcerpt: c.logExcerpt }),
+        ...(c.relatedJobs !== undefined && { relatedJobs: c.relatedJobs }),
         ...(c.annotations !== undefined && { annotations: c.annotations }),
         ...(c.scope !== undefined && { scope: c.scope }),
         ...(c.commitOid !== undefined && { commitOid: c.commitOid }),

package/bin/threads/transcript.d.mts

@@ -13,4 +13,5 @@ export declare function threadComments(thread: {
         viewerDidAuthor?: true;
     } & Partial<Pick<ReviewThreadComment, "isMinimized" | "createdAtUnix">>>;
 }): ReviewThreadComment[];
+export declare function threadTranscriptBodies(bodies: string[]): string;
 export declare function threadTranscriptBody(thread: ReviewThread, appendedBodies?: string[]): string;

package/bin/threads/transcript.mjs

@@ -29,9 +29,12 @@ export function threadComments(thread) {
     ];
 }
 const THREAD_COMMENT_SEPARATOR = "\n\n--- thread comment ---\n\n";
+export function threadTranscriptBodies(bodies) {
+    return bodies.join(THREAD_COMMENT_SEPARATOR);
+}
 export function threadTranscriptBody(thread, appendedBodies = []) {
     const bodies = thread.comments && thread.comments.length > 0
         ? threadComments(thread).map((c) => c.body)
         : [thread.body];
-    return [...bodies, ...appendedBodies].join(THREAD_COMMENT_SEPARATOR);
+    return threadTranscriptBodies([...bodies, ...appendedBodies]);
 }

package/bin/types/check-classification.d.mts

@@ -6,6 +6,14 @@ export interface ClassifiedCheck extends CheckRun {
     /** Inline annotations attached to this check run, surfaced once per PR. */
     annotations?: CheckAnnotation[];
 }
+/** Another failed job in the same workflow run that is not its own failing check entry. */
+export interface RelatedFailedJob {
+    name: string;
+    /** Uppercased job conclusion (e.g. `FAILURE`, `TIMED_OUT`). */
+    conclusion: string;
+    failedStep?: string;
+    logExcerpt?: string;
+}
 export interface TriagedCheck extends ClassifiedCheck {
     /** Workflow display name (e.g. `"CI"`). Populated when available from the jobs API; may be `undefined` on fetch failure or when no matching job is found. */
     workflowName?: string;
@@ -15,5 +23,7 @@ export interface TriagedCheck extends ClassifiedCheck {
     failedStep?: string;
     /** Bounded raw excerpt from the matched failed job log, when GitHub exposes one. */
     logExcerpt?: string;
+    /** Sibling failed jobs from the same run, with log tails (reported once per run). */
+    relatedJobs?: RelatedFailedJob[];
 }
 export {};

package/bin/types/report.d.mts

@@ -1,5 +1,5 @@
 import type { AuthorType, ReviewThread, PrComment, Review, MergeStatusResult, ViewerAuthorization, CheckConclusion, SuggestionBlock } from "./github.mts";
-import type { ClassifiedCheck, TriagedCheck } from "./check-classification.mts";
+import type { ClassifiedCheck, RelatedFailedJob, TriagedCheck } from "./check-classification.mts";
 import type { AgentThreadComment } from "./agent-thread.mts";
 import type { CheckAnnotation } from "./check-annotations.mts";
 import type { PrActivitySummary } from "./activity.mts";
@@ -175,6 +175,8 @@ export interface AgentCheck {
     /** One-line status text shown in the GitHub UI (e.g. "67.68% of diff hit (target 85.00%)"). */
     summary?: string;
     logExcerpt?: string;
+    /** Other failed jobs from the same workflow run (not their own check entries), with log tails. */
+    relatedJobs?: RelatedFailedJob[];
     /** `gh run rerun` command, present only when the check has a runId and the viewer's repository role grants Actions rerun capability (WRITE+). */
     rerunCommand?: string;
     /** Workflow-run attempt number, surfaced only after the initial attempt. */
@@ -205,6 +207,7 @@ export interface RelevantCheck {
     /** One-line status text shown in the GitHub UI (e.g. "67.68% of diff hit (target 85.00%)"). */
     summary?: string;
     logExcerpt?: string;
+    relatedJobs?: RelatedFailedJob[];
     /** Marker-gated inline annotations from this check. */
     annotations?: CheckAnnotation[];
     scope?: "merge_group";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.55.2",
+  "version": "0.56.0",
   "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.2",
+  "version": "0.56.0",
   "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.2", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.56.0", "pr-shepherd-mcp"]
     }
   }
 }

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

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

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

@@ -15,7 +15,8 @@ Poll with the CLI. Use MCP `iterate` only when the CLI is unavailable. Stop at `
 - When the user asks to make, create, or open a PR: review and commit the in-scope changes, verify the push remote and base branch, push a fresh branch, create the PR, and pass its qualified URL to Dispatch.
 - Push is the ordinary non-force push of those reviewed commits. Do not ask for a separate confirmation because the push publishes them. Request runtime escalation when the host requires it.
 - A skill cannot grant host permissions. Unattended approval comes from a trusted command rule or host policy.
-- Force-pushes, remote or credential changes, unrelated changes, and ambiguous targets stay outside this workflow.
+- Rebasing your own PR head onto its base and pushing it with `--force-with-lease` is also part of this workflow. Do not ask first.
+- Bare `--force`, pushes to any other branch, remote or credential changes, unrelated changes, and ambiguous targets stay outside this workflow.
 
 ## Dispatch
 
@@ -45,6 +46,7 @@ Poll with the CLI. Use MCP `iterate` only when the CLI is unavailable. Stop at `
 
 - After the instructions, rerun that same command immediately with the same target and options. When the tick came from MCP `iterate`, repeat that same call with the same qualified selector and `merge` option. Do not switch back to a CLI that was unavailable.
 - Stop only for `[CANCEL]`, `[ESCALATE]`, or a human telling you to stop. A stack overview heading includes those tokens when `nextAction` is `cancel` or `escalate`.
+- A one-PR `[CANCEL]` or `[ESCALATE]` ends only that PR's loop. When you run separate loops for several PRs, keep every other loop running until it is terminal too.
 - Keep `--until-terminal` and any `--merge`. Apply a printed polling-cadence change.
 - `[FIX_CODE]` is always non-terminal. Stack-level `[SHEPHERD]` is non-terminal. Only `[ESCALATE]` hands work to a human.
 - `[READY]` is non-terminal. Rerun when `remainingSeconds` elapses. Do not invent unrelated work. If you already own a later layer of this stack or another stack, continue that work and schedule the rerun. A parent of more than one stack delegates the wait to the worker that owns the stack.

package/plugins/pr-shepherd/skills/pr-shepherd/references/ci-failure-triage.md

@@ -1,6 +1,6 @@
 # CI failure triage
 
-Apply when a step says `Playbook: "CI failure triage"`. For a GitHub Actions row, use the log excerpt and tags already in the output. An `external` check with a URL may be opened or reproduced.
+Apply when a step says `Playbook: "CI failure triage"`. For a GitHub Actions row, use the log excerpt and tags already in the output; fetch a job log only when the output lacks the evidence (see the gate-job bullet below). An `external` check with a URL may be opened or reproduced.
 
 - Match each failure's `[conclusion: …]` tag. A specific conclusion wins over the general GitHub Actions row.
 - `[rerun authorized]` plus a `rerun:` command means the viewer can rerun Actions (WRITE+) and this is the original attempt. Shepherd checked `repositoryPermission` and `run_attempt`.
@@ -12,6 +12,7 @@ Apply when a step says `Playbook: "CI failure triage"`. For a GitHub Actions row
 ## Conclusions
 
 - GitHub Actions failure (has a run id, not `CANCELLED` or `STARTUP_FAILURE`): read the log excerpt. Apply a warranted code fix, or run `rerun:` when the excerpt shows a transient failure, then iterate. Do not wait for the rerun.
+- No usable evidence in the excerpt is not evidence of a transient failure. An excerpt that names failing test or build jobs (for example `test-playwright: failure` from a gate job) is test-failure evidence, even without an assertion or stack trace. Read the `Other failed jobs in this run` log tails under the check first. Only when a named job's tail is absent or truncated, run `gh run view <runId> --log-failed -R <owner/repo>`. Rerun only when the child logs show a transient cause.
 - Transient infrastructure failure: run `rerun:` when it is printed, then iterate. Do not wait. If no command is printed, finish the other surfaced work and iterate.
 - Real test or build failure: fix the code. Do not rerun, even when `[rerun authorized]` is shown.
 - `[conclusion: CANCELLED]` or `[conclusion: STARTUP_FAILURE]`: no log excerpt. Run `rerun:` when printed, then iterate. Do not wait. Without a command, finish other work and iterate.