pr-shepherd 0.25.3 → 0.26.0

package/bin/cli/journal-handler.mjs

@@ -0,0 +1,79 @@
+import { runJournal } from "../commands/journal/index.mjs";
+import { parsePrNumber } from "./args.mjs";
+import { USAGE } from "./help.mjs";
+export async function handleJournal(args) {
+    for (const a of args) {
+        if (!a.startsWith("--"))
+            continue;
+        if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
+            continue;
+        process.stderr.write(`pr-shepherd: journal: unknown flag: "${a}"\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const { prNumber, extra } = parseJournalArgs(args);
+    const rawItem = extra[0];
+    if (!rawItem) {
+        process.stderr.write(`${USAGE.journal}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const dryRun = args.includes("--dry-run");
+    const jsonOut = args.some((a) => a === "--format=json") ||
+        args.some((a, i) => a === "--format" && args[i + 1] === "json");
+    try {
+        const result = await runJournal({ prNumber, rawItem, dryRun });
+        if (jsonOut) {
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(`${formatJournalResult(result)}\n`);
+        }
+    }
+    catch (e) {
+        process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
+        process.exitCode = 1;
+    }
+}
+function parseJournalArgs(args) {
+    const flagConsumedIndices = new Set();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--format" && i + 1 < args.length && !args[i + 1].startsWith("--")) {
+            flagConsumedIndices.add(i);
+            flagConsumedIndices.add(i + 1);
+        }
+    }
+    let prNumber;
+    const extra = [];
+    for (let i = 0; i < args.length; i++) {
+        if (flagConsumedIndices.has(i))
+            continue;
+        const a = args[i];
+        if (a.startsWith("--"))
+            continue;
+        if (prNumber === undefined) {
+            const n = parsePrNumber(a);
+            if (n !== null) {
+                prNumber = n;
+                continue;
+            }
+        }
+        extra.push(a);
+    }
+    return { prNumber, extra };
+}
+function formatJournalResult(result) {
+    if (result.dryRun) {
+        const lines = ["Dry run — no body change written."];
+        if (result.previewBody !== undefined) {
+            lines.push("", result.previewBody);
+        }
+        return lines.join("\n");
+    }
+    if (!result.mutated)
+        return "No change — entry already present.";
+    if (!result.sectionExisted)
+        return `Created ## Shepherd Journal section in PR #${result.prNumber}.`;
+    return `Appended to ## Shepherd Journal in PR #${result.prNumber}.`;
+}

package/bin/cli/poll-handler.mjs

@@ -32,6 +32,7 @@ export async function handlePoll(args) {
         noAutoCancelActionable: flags.noAutoCancelActionable,
         intervalSeconds,
         timeoutSeconds,
+        quietStatus: hasFlag(extra, "--quiet-status"),
     });
     emitIterateResult(result, {
         format: globalOpts.format,

package/bin/cli-parser.mjs

@@ -1,26 +1,4 @@
-/**
- * CLI argument parsing and subcommand dispatch for pr-shepherd.
- *
- * Usage:
- *   pr-shepherd --version
- *   pr-shepherd [PR] [--interval 45s] [--timeout 4m] [--format text|json] [--ready-delay Nm]
- *                  [--stall-timeout <duration>] [--no-auto-mark-ready]
- *                  [--no-auto-cancel-actionable]
- *   pr-shepherd resolve [PR] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
- *                            [--reply-thread-ids A,B] [--dismiss-review-ids Q]
- *                            [--message MSG] [--require-sha SHA]
- *   pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [--description DESC]
- *                                      [--format text|json]
- *   pr-shepherd mark-files-as-viewed [PR] [files...] [--tests] [--match REGEX]
- *                                           [--format text|json]
- *   pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]
- *                              [--stall-timeout <duration>] [--no-auto-mark-ready]
- *                              [--no-auto-cancel-actionable]
- *   pr-shepherd poll [PR] [--interval 30s] [--timeout 5m] [--format text|json] [--ready-delay Nm]
- *                         [--stall-timeout <duration>] [--no-auto-mark-ready]
- *                         [--no-auto-cancel-actionable]
- *   pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]
- */
+/** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
 import { readFileSync } from "node:fs";
 import { runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
@@ -29,6 +7,7 @@ import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-
 import { USAGE, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
+import { handleJournal } from "./cli/journal-handler.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
 import { setupLog } from "./log/setup.mjs";
@@ -91,6 +70,9 @@ export async function main(argv) {
         case "clean":
             await handleClean(args.slice(1));
             break;
+        case "journal":
+            await handleJournal(args.slice(1));
+            break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
             process.stderr.write(`${USAGE.top}\n`);

package/bin/commands/check-terminal-report.mjs

@@ -32,5 +32,6 @@ export function buildTerminalReport(prNumber, repo, batchData, mergeStatus, stat
         editedSummaries: [],
         approvedReviews: [],
         branchProtection: batchData.branchProtection,
+        activity: batchData.activity,
     };
 }

package/bin/commands/check.mjs

@@ -16,6 +16,8 @@ import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay } from "../comments/review-visibility.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
 import { normalizeBotUsernames } from "../comments/authors.mjs";
+import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
+import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -46,10 +48,13 @@ export async function runCheck(opts) {
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const seenMap = await loadSeenMap(stateKey);
     const botUsernames = normalizeBotUsernames(config.botUsernames);
+    const ruleSet = await loadRules(discoverRuleFiles(process.cwd()));
+    const classifyIndex = buildClassifyIndex(ruleSet, batchData);
+    const partition = partitionBatch(classifyIndex, batchData);
     const triaged = await attachUnseenCheckAnnotations(triagedBase, seenMap, prNumber);
-    const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized);
-    const visibleCommentClassification = classifyVisibleComments(batchData.comments, seenMap, config.iterate.minimizeComments, botUsernames);
-    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads, seenMap, botUsernames);
+    const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized && !partition.suppressedCommentIds.has(c.id));
+    const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
+    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id)), seenMap, botUsernames);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
         const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
@@ -60,7 +65,8 @@ export async function runCheck(opts) {
     const firstLookSummaries = [];
     const editedSummaries = [];
     const seenSummaries = [];
-    for (const r of batchData.reviewSummaries) {
+    const unseenReviewSummaries = batchData.reviewSummaries.filter((r) => !partition.suppressedReviewSummaryIds.has(r.id));
+    for (const r of unseenReviewSummaries) {
         const cls = classifyItem(r.id, r.body, seenMap);
         if (cls === "new")
             firstLookSummaries.push(r);
@@ -69,7 +75,7 @@ export async function runCheck(opts) {
         else
             seenSummaries.push(r);
     }
-    const changesRequestedReviewVisibility = classifyReviewsForDisplay(batchData.changesRequestedReviews, seenMap);
+    const changesRequestedReviewVisibility = classifyReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
     await Promise.allSettled([
         ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
@@ -78,14 +84,26 @@ export async function runCheck(opts) {
         ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
         ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
         ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+        ...batchData.comments
+            .filter((c) => partition.suppressedCommentIds.has(c.id))
+            .map((c) => markSeen(stateKey, c.id, c.body)),
+        ...batchData.reviewThreads
+            .filter((t) => partition.suppressedThreadIds.has(t.id))
+            .map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
+        ...batchData.reviewSummaries
+            .filter((r) => partition.suppressedReviewSummaryIds.has(r.id))
+            .map((r) => markSeen(stateKey, r.id, r.body)),
+        ...batchData.changesRequestedReviews
+            .filter((r) => partition.suppressedChangesRequestedIds.has(r.id))
+            .map((r) => markSeen(stateKey, r.id, r.body)),
     ]);
     await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
-    const changesRequestedReviewCount = batchData.changesRequestedReviews.length;
+    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)).length;
     const approvedReviews = approvedReviewVisibility.visible;
     let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
     if (status === "READY" && !didRefreshMergeability) {
-        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length);
+        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount);
         batchData = refreshed.batchData;
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
@@ -113,10 +131,16 @@ export async function runCheck(opts) {
             autoResolved: [],
             autoResolveErrors: [],
             firstLook: threadVisibility.firstLookThreads,
+            ...(partition.ruleAutoResolveThreadIds.length > 0
+                ? { ruleAutoResolveIds: partition.ruleAutoResolveThreadIds }
+                : undefined),
         },
         comments: {
             actionable: visibleCommentClassification.actionable,
-            minimizeIds: visibleCommentClassification.minimizeIds,
+            minimizeIds: [
+                ...visibleCommentClassification.minimizeIds,
+                ...partition.ruleAutoResolveCommentIds,
+            ],
             firstLook: firstLookComments,
         },
         changesRequestedReviews,
@@ -124,6 +148,10 @@ export async function runCheck(opts) {
         firstLookSummaries,
         editedSummaries,
         approvedReviews,
+        ...(partition.ruleAutoResolveReviewSummaryIds.length > 0
+            ? { ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds }
+            : undefined),
         branchProtection: batchData.branchProtection,
+        activity: batchData.activity,
     };
 }

package/bin/commands/iterate/classify.mjs

@@ -12,7 +12,7 @@ function dedupeIds(ids) {
     }
     return out;
 }
-export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all", botUsernames = new Set(), unresolvedThreads = []) {
+export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all", botUsernames = new Set(), unresolvedThreads = [], ruleAutoResolveIds = []) {
     const blockedReviewIds = new Set(unresolvedThreads.flatMap((t) => (t.reviewId !== undefined ? [t.reviewId] : [])));
     // First-look and seen summaries go into the minimize mutation; edited summaries do NOT —
     // they are already minimized server-side (body changed after minimize was applied).
@@ -21,6 +21,11 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
         .filter((r) => shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames))
         .filter((r) => !blockedReviewIds.has(r.id))
         .map((r) => r.id);
+    // Rule-matched summaries are already suppressed from agent output; bypass normal policy gates.
+    for (const id of ruleAutoResolveIds) {
+        if (!minimizeIds.includes(id))
+            minimizeIds.push(id);
+    }
     if (minimizeApprovals) {
         const surfacedApprovals = [];
         for (const r of approvals) {
@@ -43,14 +48,18 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
         surfacedApprovals: approvals,
     };
 }
-export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, _reviews, checks, prNumber, botUsernames = new Set()) {
+export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, _reviews, checks, prNumber, botUsernames = new Set(), ruleAutoResolveThreadIds = []) {
     const allThreads = [...threads, ...resolutionOnlyThreads];
     const replyThreadIds = dedupeIds(allThreads
         .filter((t) => isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames))
         .map((t) => t.id));
-    const resolveThreadIds = dedupeIds(allThreads
-        .filter((t) => !isHumanAuthor(t) || isConfiguredBotAuthor(t, botUsernames))
-        .map((t) => t.id));
+    // Rule-matched threads bypass the author check (human-author guard still applies in resolve-mutate).
+    const resolveThreadIds = dedupeIds([
+        ...allThreads
+            .filter((t) => !isHumanAuthor(t) || isConfiguredBotAuthor(t, botUsernames))
+            .map((t) => t.id),
+        ...ruleAutoResolveThreadIds,
+    ]);
     const hasReply = replyThreadIds.length > 0;
     const hasResolveOrMinimize = resolveThreadIds.length > 0 || allCommentIds.length > 0;
     if (hasReply && hasResolveOrMinimize) {

package/bin/commands/iterate/fix-code.mjs

@@ -25,7 +25,7 @@ function nextFixAttempts(stored, headSha, threads) {
     return { threadAttempts, threadBodyHashes };
 }
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);
@@ -76,7 +76,7 @@ export async function handleFixCode(ctx) {
     const inProgressRunIds = pushLikely ? buildInProgressRunIds(report, cancelledSet) : [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, botUsernames);
+    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, botUsernames, ruleAutoResolveThreadIds);
     // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
     // would need the correct base to rebase safely. This is a conservative guard, not a
     // prediction that the agent *will* push. Intentionally broader than `pushLikely` above:

package/bin/commands/iterate/helpers.mjs

@@ -59,6 +59,15 @@ export function buildRelevantChecks(report) {
     });
     return [...passing, ...failing];
 }
+export function buildActiveChecks(report) {
+    return report.checks.inProgress.map((c) => ({
+        name: c.name,
+        status: c.status,
+        runId: c.runId,
+        detailsUrl: c.detailsUrl || null,
+        ...(c.summary !== undefined && { summary: c.summary }),
+    }));
+}
 // Best-effort: cancelling a completed run is a no-op, not an error.
 export async function tryCancelRun(runId, owner, repo) {
     try {
@@ -86,6 +95,12 @@ export async function getCurrentHeadSha() {
 export function buildWaitLog(base) {
     const { summary, remainingSeconds } = base;
     const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
+    if ((base.inProgressChecks?.length ?? 0) > 0) {
+        parts.push(`active checks: ${base
+            .inProgressChecks.slice(0, 5)
+            .map((c) => c.name)
+            .join(", ")}`);
+    }
     switch (base.mergeStatus) {
         case "BLOCKED":
             if (base.reviewDecision === "REVIEW_REQUIRED")

package/bin/commands/iterate/index.mjs

@@ -4,7 +4,7 @@ import { getCurrentPrNumber } from "../../github/client.mjs";
 import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
-import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildWaitLog } from "./helpers.mjs";
+import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
@@ -49,6 +49,8 @@ export async function runIterate(opts) {
             baseBranch: report.baseBranch,
             branchProtection: report.branchProtection,
             checks: buildRelevantChecks(report),
+            inProgressChecks: buildActiveChecks(report),
+            activity: report.activity,
             action: "cancel",
             reason: report.mergeStatus.state === "MERGED" ? "merged" : "closed",
             log: `CANCEL: PR #${report.pr} is ${state} — stopping`,
@@ -58,10 +60,11 @@ export async function runIterate(opts) {
         firstLook: report.firstLookSummaries,
         seen: report.reviewSummaries,
         edited: report.editedSummaries,
-    }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [...report.threads.actionable, ...report.threads.resolutionOnly]);
+    }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [...report.threads.actionable, ...report.threads.resolutionOnly], report.ruleAutoResolveReviewSummaryIds);
     const hasActionableWork = report.threads.actionable.length > 0 ||
         report.threads.resolutionOnly.length > 0 ||
         report.threads.firstLook.length > 0 ||
+        (report.threads.ruleAutoResolveIds?.length ?? 0) > 0 ||
         report.comments.actionable.length > 0 ||
         (report.comments.minimizeIds?.length ?? 0) > 0 ||
         report.comments.firstLook.length > 0 ||
@@ -89,6 +92,8 @@ export async function runIterate(opts) {
         baseBranch: report.baseBranch,
         branchProtection: report.branchProtection,
         checks: buildRelevantChecks(report),
+        inProgressChecks: buildActiveChecks(report),
+        activity: report.activity,
     };
     if (readyState.shouldCancel) {
         await clearStallState(stallKey);
@@ -125,6 +130,7 @@ export async function runIterate(opts) {
             editedSummaries,
             surfacedApprovals,
             botUsernames,
+            ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
     const canMarkReady = report.status === "READY" &&

package/bin/commands/iterate/render.mjs

@@ -2,7 +2,9 @@ import { renderShellCommand } from "../../cli/runner.mjs";
 import { buildFailingCheckInstructions } from "./check-instructions.mjs";
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
-export const FIX_INSTRUCTION_STOP = "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.";
+// Module-private: the final "stop" step appended to every fix_code instruction list. No longer
+// re-exported now that the recheck/delay suffix that consumed it (in iterate-instructions) is gone.
+const FIX_INSTRUCTION_STOP = "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.";
 /**
  * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE`, `$HEAD_SHA`, and
  * whitespace-bearing argv entries for placeholder substitution. `$HEAD_SHA` is never in `argv` —
@@ -15,7 +17,8 @@ export function renderResolveCommand(rc) {
     }
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand) {
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, _baseBranch, // retained for call-site stability; rebase mechanics now defer to the caller
+resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand) {
     const instructions = [];
     const hasNonConflictHints = threads.length > 0 ||
         checks.length > 0 ||
@@ -39,17 +42,17 @@ export function buildFixInstructions(threads, actionableComments, checks, change
         const resolveClause = resolveCommand.hasMutations ? ", then run the `resolve:` command" : "";
         if (hasConflicts) {
             // Conflicts make push mandatory regardless of whether code edits are needed.
-            instructions.push(`The branch has merge conflicts that require rebase before merging. Apply any code edits for items ${sectionRef}, commit if edits were made, rebase onto \`origin/${baseBranch}\` per your repository's conventions, push${resolveClause}.`);
+            instructions.push(`The branch has merge conflicts that must be resolved before merging (see \`**branch**\` above). Apply any code edits for items ${sectionRef}, then commit and push${resolveClause}.`);
         }
         else {
             const skipClause = resolveCommand.hasMutations
-                ? "skip cancellation/commit/push and run the `resolve:` command"
+                ? "skip the commit/push and run the `resolve:` command"
                 : "no push is needed";
-            instructions.push(`Decide for each item ${sectionRef} whether a code change is warranted. **If any code changes are needed:** cancel in-progress runs first, apply edits, commit, rebase, push${resolveClause}. **If no code changes are needed:** ${skipClause}.`);
+            instructions.push(`Decide for each item ${sectionRef} whether a code change is warranted. **If any code changes are needed:** apply edits, commit, push${resolveClause}. **If no code changes are needed:** ${skipClause}.`);
         }
     }
     else if (hasConflicts) {
-        instructions.push(`The branch has merge conflicts — rebase onto \`origin/${baseBranch}\` per your repository's conventions to resolve them, then push.`);
+        instructions.push(`The branch has merge conflicts that must be resolved before merging (see \`**branch**\` above). Resolve them and push.`);
     }
     if (inProgressRunIds.length > 0) {
         instructions.push(`If you decide to push new commits: cancel each in-progress run listed under \`## In-progress runs\` before applying code fixes (e.g. \`gh run cancel <id>\`). Runs may complete between the tick and your action; treat cancellation errors on already-finished runs as non-fatal. Skip this step if you are only resolving threads without pushing — the existing runs remain relevant.`);
@@ -58,10 +61,15 @@ export function buildFixInstructions(threads, actionableComments, checks, change
     if (hasSuggestions)
         instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads", false));
     if (threads.length > 0 || actionableComments.length > 0) {
+        const fixSections = [];
+        if (threads.length > 0)
+            fixSections.push("`## Review threads`");
+        if (actionableComments.length > 0)
+            fixSections.push("`## Actionable comments`");
         const suggestionFallback = hasSuggestions
             ? ` When applying a \`[suggestion]\` thread manually (e.g. after a failed \`commit-suggestion\` run), replace the exact line range shown in the heading (\`path:startLine-endLine\`) with the replacement shown in its \`Replaces lines …\` block verbatim — an empty replacement deletes those lines, a single blank line replaces the range with one blank line.`
             : "";
-        instructions.push(`Apply code fixes: read and edit each file referenced under \`## Review threads\` and \`## Actionable comments\` above.${suggestionFallback}`);
+        instructions.push(`Apply code fixes: read and edit each file referenced under ${fixSections.join(" and ")} above.${suggestionFallback}`);
     }
     if (resolutionOnlyThreads.length > 0) {
         instructions.push(`Review the threads under \`## Review threads to resolve\`. Human-authored threads are replied to by the \`resolve:\` command shown below; Shepherd does not resolve them. Bot/non-human threads are included in \`--resolve-thread-ids\`.`);
@@ -73,8 +81,6 @@ export function buildFixInstructions(threads, actionableComments, checks, change
     if (changesRequestedReviews.length > 0) {
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
     }
-    if (hasNonConflictHints)
-        instructions.push(`If you applied code edits: commit them with a descriptive message, then rebase onto \`origin/${baseBranch}\` per your repository's conventions before pushing.`);
     if (resolveOnlyCommand?.hasMutations)
         instructions.push(`Run the \`resolve-only:\` command shown above — no substitutions needed.`);
     if (resolveCommand.hasMutations) {

package/bin/commands/iterate/stall.mjs

@@ -8,9 +8,11 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
     ].sort();
     const threads = report.threads.actionable.map((t) => t.id).sort();
     const resolutionOnlyThreads = report.threads.resolutionOnly.map((t) => t.id).sort();
+    const ruleAutoResolveThreads = (report.threads.ruleAutoResolveIds ?? []).sort((a, b) => a.localeCompare(b));
     const comments = report.comments.actionable.map((c) => c.id).sort();
     const reviews = report.changesRequestedReviews.map((r) => r.id).sort();
     const summaries = [...reviewSummaryIds].sort();
+    const ruleAutoResolveSummaries = (report.ruleAutoResolveReviewSummaryIds ?? []).sort((a, b) => a.localeCompare(b));
     return JSON.stringify({
         action,
         headSha,
@@ -21,9 +23,11 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
         checks,
         threads,
         resolutionOnlyThreads,
+        ruleAutoResolveThreads,
         comments,
         reviews,
         summaries,
+        ruleAutoResolveSummaries,
     });
 }
 export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds) {

package/bin/commands/journal/index.mjs

@@ -0,0 +1,26 @@
+import { getRepoInfo, getPullRequestBody, updatePullRequestBody, getCurrentPrNumber, } from "../../github/client.mjs";
+import { validateJournalItem, appendJournalItem } from "./transform.mjs";
+export async function runJournal(opts) {
+    const validation = validateJournalItem(opts.rawItem);
+    if (!validation.ok) {
+        throw new Error(validation.error);
+    }
+    const { item } = validation;
+    const { owner, name } = await getRepoInfo();
+    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
+    if (!prNumber) {
+        throw new Error("PR number is required: no PR number provided and none found for current branch");
+    }
+    const { nodeId, body } = await getPullRequestBody(prNumber, owner, name);
+    const { body: newBody, mutated, sectionExisted } = appendJournalItem(body, item);
+    if (mutated && !opts.dryRun) {
+        await updatePullRequestBody(nodeId, newBody);
+    }
+    return {
+        prNumber,
+        mutated,
+        sectionExisted,
+        dryRun: opts.dryRun,
+        ...(opts.dryRun ? { previewBody: newBody } : {}),
+    };
+}

package/bin/commands/journal/transform.mjs

@@ -0,0 +1,112 @@
+import { SHEPHERD_JOURNAL_SECTION, SHEPHERD_JOURNAL_SECTION_PATTERN, } from "../shepherd-journal.mjs";
+/** Validates that the input is a properly formed markdown list item. */
+export function validateJournalItem(input) {
+    const lines = input.split("\n").map((l) => l.trimEnd());
+    const nonBlank = lines.filter((l) => l.trim() !== "");
+    if (nonBlank.length === 0) {
+        return { ok: false, error: 'journal item must not be empty; expected a "- <text>" list item' };
+    }
+    if (!/^- \S/.test(nonBlank[0])) {
+        return {
+            ok: false,
+            error: `journal item must start with "- <text>"; got: ${JSON.stringify(nonBlank[0].slice(0, 40))}`,
+        };
+    }
+    for (const line of nonBlank.slice(1)) {
+        if (line.startsWith("#")) {
+            return {
+                ok: false,
+                error: "journal item lines must not start with # (would break section structure)",
+            };
+        }
+    }
+    const trimmed = lines
+        .map((l) => l.trimEnd())
+        .join("\n")
+        .trim();
+    return { ok: true, item: trimmed };
+}
+/**
+ * Appends a validated list item to the ## Shepherd Journal section of a PR body.
+ * Creates the section at the end if absent. Skips if the exact item is already present (idempotent).
+ */
+export function appendJournalItem(body, item) {
+    const lines = body.split("\n");
+    const bounds = findSectionBounds(lines);
+    if (!bounds) {
+        return createSection(lines, item);
+    }
+    const { headingIdx, endIdx } = bounds;
+    const sectionLines = lines.slice(headingIdx + 1, endIdx);
+    if (itemAlreadyPresent(sectionLines, item)) {
+        return { body, mutated: false, sectionExisted: true };
+    }
+    return appendToSection(lines, headingIdx, endIdx, sectionLines, item);
+}
+function findSectionBounds(lines) {
+    let inFence = false;
+    let headingIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
+            inFence = !inFence;
+            continue;
+        }
+        if (!inFence) {
+            if (headingIdx === -1) {
+                if (SHEPHERD_JOURNAL_SECTION_PATTERN.test(lines[i].trimEnd())) {
+                    headingIdx = i;
+                }
+            }
+            else if (/^#{1,2} /.test(lines[i])) {
+                return { headingIdx, endIdx: i };
+            }
+        }
+    }
+    if (headingIdx === -1)
+        return null;
+    return { headingIdx, endIdx: lines.length };
+}
+function itemAlreadyPresent(sectionLines, item) {
+    const itemLines = item.split("\n").map((l) => l.trimEnd());
+    const normalizedSection = sectionLines.map((l) => l.trimEnd());
+    for (let i = 0; i <= normalizedSection.length - itemLines.length; i++) {
+        let match = true;
+        for (let j = 0; j < itemLines.length; j++) {
+            if (normalizedSection[i + j] !== itemLines[j]) {
+                match = false;
+                break;
+            }
+        }
+        if (match)
+            return true;
+    }
+    return false;
+}
+function appendToSection(lines, headingIdx, endIdx, sectionLines, item) {
+    const before = lines.slice(0, headingIdx + 1);
+    const after = lines.slice(endIdx);
+    // Strip trailing blank lines from section body.
+    let sectionEnd = sectionLines.length;
+    while (sectionEnd > 0 && sectionLines[sectionEnd - 1].trim() === "") {
+        sectionEnd--;
+    }
+    const trimmedSection = sectionLines.slice(0, sectionEnd);
+    // Insert blank line after heading when section was empty, then the item.
+    const newSection = trimmedSection.length === 0
+        ? ["", ...item.split("\n")]
+        : [...trimmedSection, ...item.split("\n")];
+    // One blank line before the next section (or trailing newline at EOF).
+    const newBody = [...before, ...newSection, ...(after.length > 0 ? ["", ...after] : [])].join("\n");
+    return { body: newBody, mutated: true, sectionExisted: true };
+}
+function createSection(lines, item) {
+    // Strip trailing blank lines from the existing body.
+    let end = lines.length;
+    while (end > 0 && lines[end - 1].trim() === "") {
+        end--;
+    }
+    const trimmedLines = lines.slice(0, end);
+    const newBody = [...trimmedLines, "", SHEPHERD_JOURNAL_SECTION, "", ...item.split("\n")].join("\n");
+    return { body: newBody, mutated: true, sectionExisted: false };
+}