pr-shepherd 0.10.2 → 0.10.3

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.10.2",
+  "version": "0.10.3",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -128,6 +128,7 @@ Recommendations:
 - Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. As it uses `/loop`, it will continue working when your rate limit window is reset. The loop cancels automatically when the PR is merged, closed, or after the ready-delay elapses.
 - Instruct your agents to write comments in a single review (comment, changes requested, or approved). This allows the review's comments/threads to be minimized or resolved together, keeping your pull request history clean. If you write inline comments outside of a review, each comment would still show up in the pull request history and take up space.
 - Avoid sticky comments as they will continue to be hidden. Instead, just make a new comment, especially on reviews. If you really want sticky comments, instruct your agent to unhide/unminimize them when updating them.
+- Avoid having automation edit comments, reviews, or threads in place because updated items get minimized. Instead, always make a new review, comment, thread, etc.
 
 ## Design Principles
 

package/bin/cli/fix-formatter.mjs

@@ -63,6 +63,13 @@ export function formatFixCodeResult(header, result) {
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
         }
     }
+    if (result.fix.editedSummaries.length > 0) {
+        sections.push("## Review summaries (edited since first look — already minimized; do not re-minimize)");
+        for (const r of result.fix.editedSummaries) {
+            sections.push(`### \`reviewId=${r.id}\` (@${r.author})`);
+            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
+        }
+    }
     const firstLookSummaryIds = new Set(result.fix.firstLookSummaries.map((r) => r.id));
     const seenSummaryIds = result.fix.reviewSummaryIds.filter((id) => !firstLookSummaryIds.has(id));
     if (seenSummaryIds.length > 0) {
@@ -84,7 +91,8 @@ export function formatFixCodeResult(header, result) {
             bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
         for (const c of result.fix.firstLookComments) {
-            bullets.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
+            const editedSuffix = c.edited ? ", edited" : "";
+            bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
         }
         sections.push(bullets.join("\n"));
     }

package/bin/cli/formatters.mjs

@@ -44,7 +44,8 @@ export function formatFetchResult(result) {
             bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
         for (const c of result.firstLookComments) {
-            bullets.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
+            const editedSuffix = c.edited ? ", edited" : "";
+            bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
         }
         sections.push(bullets.join("\n"));
     }

package/bin/cli/iterate-lean.mjs

@@ -55,6 +55,9 @@ export function projectIterateLean(result) {
                     ...(result.fix.firstLookSummaries.length > 0 && {
                         firstLookSummaries: result.fix.firstLookSummaries,
                     }),
+                    ...(result.fix.editedSummaries.length > 0 && {
+                        editedSummaries: result.fix.editedSummaries,
+                    }),
                     ...(result.fix.surfacedApprovals.length > 0 && {
                         surfacedApprovals: result.fix.surfacedApprovals,
                     }),

package/bin/cli/list-formatters.mjs

@@ -6,7 +6,10 @@ export function renderBodyPreview(body) {
     return firstLine.slice(0, BODY_PREVIEW_MAX);
 }
 export function renderFirstLookStatusTag(t) {
-    return t.autoResolved ? "[status: outdated, auto-resolved]" : `[status: ${t.firstLookStatus}]`;
+    const editedSuffix = t.edited ? ", edited" : "";
+    return t.autoResolved
+        ? `[status: outdated, auto-resolved${editedSuffix}]`
+        : `[status: ${t.firstLookStatus}${editedSuffix}]`;
 }
 export function renderThreadBullet(t, opts = {}) {
     const link = t.url ? ` [↗](${t.url})` : "";

package/bin/cli-parser.iterate-fixtures.mjs

@@ -31,6 +31,7 @@ export function makeIterateResult(action = "wait") {
                 actionableComments: [],
                 reviewSummaryIds: [],
                 firstLookSummaries: [],
+                editedSummaries: [],
                 surfacedApprovals: [],
                 checks: [],
                 changesRequestedReviews: [],

package/bin/commands/check.mjs

@@ -1,17 +1,3 @@
-/**
- * `shepherd check [PR]`
- *
- * Read-only snapshot of PR status. Fetches CI + comments + merge status in
- * one GraphQL request, applies all classifiers, and returns a ShepherdReport.
- *
- * Exit codes:
- *   0  READY — all checks passed, no unresolved threads, CLEAN merge status.
- *   1  FAILING — CI has red checks, or merge has conflicts.
- *   1  PENDING — CI passing but merge blocked (BLOCKED, UNSTABLE, or BEHIND).
- *   1  UNKNOWN — merge state unresolvable.
- *   2  IN_PROGRESS — CI checks still running.
- *   3  UNRESOLVED_COMMENTS — CI ok but actionable threads remain.
- */
 import { fetchPrBatch } from "../github/batch.mjs";
 import { getRepoInfo, getCurrentPrNumber, getMergeableState } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
@@ -21,7 +7,7 @@ import { autoResolveOutdated } from "../comments/resolve.mjs";
 import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { computeStatus } from "./check-status.mjs";
-import { loadSeenSet, markSeen } from "../state/seen-comments.mjs";
+import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -29,14 +15,10 @@ export async function runCheck(opts) {
         throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
     }
     const config = loadConfig();
-    // Only paginate APPROVED reviews when the caller will actually minimize them.
-    // Otherwise the first-page cap of 50 (already in the batch) is plenty — no extra round-trip.
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
     const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
     let batchData = result.data;
-    // GraphQL sometimes returns UNKNOWN for mergeable/mergeStateStatus while the
-    // REST API already has the correct value. Fall back to REST in that case.
-    // Skip for non-OPEN PRs — REST also returns UNKNOWN for merged/closed PRs.
+    // Fall back to REST when GraphQL returns UNKNOWN — skip for non-OPEN PRs.
     if ((batchData.state ?? "OPEN") === "OPEN" &&
         (batchData.mergeable === "UNKNOWN" || batchData.mergeStateStatus === "UNKNOWN")) {
         const restState = await getMergeableState(prNumber, repo.owner, repo.name);
@@ -59,7 +41,6 @@ export async function runCheck(opts) {
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = batchData.comments.filter((c) => !c.isMinimized);
-    // Auto-resolve outdated threads.
     const outdated = getOutdatedThreads(unresolvedThreads);
     let autoResolved = [];
     let autoResolveErrors = [];
@@ -69,51 +50,70 @@ export async function runCheck(opts) {
         autoResolveErrors = errors;
     }
     const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated);
-    // First-look: collect previously-hidden items not yet seen by the agent.
     const outdatedCandidates = batchData.reviewThreads.filter((t) => t.isOutdated);
     const resolvedCandidates = batchData.reviewThreads.filter((t) => t.isResolved && !t.isOutdated);
     const minimizedThreadCandidates = batchData.reviewThreads.filter((t) => t.isMinimized && !t.isResolved && !t.isOutdated);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized);
-    const seenSet = await loadSeenSet(stateKey);
+    const seenMap = await loadSeenMap(stateKey);
     const autoResolvedIds = new Set(autoResolved.map((t) => t.id));
     const firstLookThreads = [
-        ...outdatedCandidates
-            .filter((t) => !seenSet.has(t.id))
-            .map((t) => ({
-            ...t,
-            firstLookStatus: "outdated",
-            autoResolved: autoResolvedIds.has(t.id),
-        })),
-        ...resolvedCandidates
-            .filter((t) => !seenSet.has(t.id))
-            .map((t) => ({ ...t, firstLookStatus: "resolved" })),
-        ...minimizedThreadCandidates
-            .filter((t) => !seenSet.has(t.id))
-            .map((t) => ({ ...t, firstLookStatus: "minimized" })),
+        ...outdatedCandidates.flatMap((t) => {
+            const cls = classifyItem(t.id, t.body, seenMap);
+            if (cls === "unchanged")
+                return [];
+            const base = {
+                ...t,
+                firstLookStatus: "outdated",
+                autoResolved: autoResolvedIds.has(t.id),
+            };
+            return cls === "edited" ? [{ ...base, edited: true }] : [base];
+        }),
+        ...resolvedCandidates.flatMap((t) => {
+            const cls = classifyItem(t.id, t.body, seenMap);
+            if (cls === "unchanged")
+                return [];
+            const base = { ...t, firstLookStatus: "resolved" };
+            return cls === "edited" ? [{ ...base, edited: true }] : [base];
+        }),
+        ...minimizedThreadCandidates.flatMap((t) => {
+            const cls = classifyItem(t.id, t.body, seenMap);
+            if (cls === "unchanged")
+                return [];
+            const base = { ...t, firstLookStatus: "minimized" };
+            return cls === "edited" ? [{ ...base, edited: true }] : [base];
+        }),
     ];
-    const firstLookComments = minimizedCommentCandidates
-        .filter((c) => !seenSet.has(c.id))
-        .map((c) => ({ ...c, firstLookStatus: "minimized" }));
-    // Split review summaries into first-look (unseen — surface body) vs seen (minimize silently).
-    const firstLookSummaries = batchData.reviewSummaries.filter((r) => !seenSet.has(r.id));
-    const seenSummaries = batchData.reviewSummaries.filter((r) => seenSet.has(r.id));
-    // Mark first-look items as seen (best-effort — markSeen never throws).
+    const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
+        const cls = classifyItem(c.id, c.body, seenMap);
+        if (cls === "unchanged")
+            return [];
+        const base = { ...c, firstLookStatus: "minimized" };
+        return cls === "edited" ? [{ ...base, edited: true }] : [base];
+    });
+    const firstLookSummaries = [];
+    const editedSummaries = [];
+    const seenSummaries = [];
+    for (const r of batchData.reviewSummaries) {
+        const cls = classifyItem(r.id, r.body, seenMap);
+        if (cls === "new")
+            firstLookSummaries.push(r);
+        else if (cls === "edited")
+            editedSummaries.push(r);
+        else
+            seenSummaries.push(r);
+    }
     await Promise.allSettled([
-        ...firstLookThreads.map((t) => markSeen(stateKey, t.id)),
-        ...firstLookComments.map((c) => markSeen(stateKey, c.id)),
-        ...firstLookSummaries.map((r) => markSeen(stateKey, r.id)),
+        ...firstLookThreads.map((t) => markSeen(stateKey, t.id, t.body)),
+        ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
+        ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
     ]);
-    // Actionable: all active threads and all visible comments (no classification — LLM handles triage).
     const actionableThreads = activeThreads;
     const actionableComments = visibleComments;
-    // Derive merge status.
     const mergeStatus = deriveMergeStatus(batchData);
-    // Derive blockedByFilteredCheck ghost state.
     const blockedByFilteredCheck = mergeStatus.status === "BLOCKED" &&
         !verdict.anyFailing &&
         !verdict.anyInProgress &&
         verdict.filteredNames.length > 0;
-    // Compute overall status.
     const status = computeStatus(verdict, actionableThreads.length, actionableComments.length, mergeStatus, batchData.changesRequestedReviews.length);
     return {
         pr: prNumber,
@@ -144,6 +144,7 @@ export async function runCheck(opts) {
         changesRequestedReviews: batchData.changesRequestedReviews,
         reviewSummaries: seenSummaries,
         firstLookSummaries,
+        editedSummaries,
         approvedReviews: batchData.approvedReviews,
     };
 }

package/bin/commands/iterate/classify.mjs

@@ -1,13 +1,24 @@
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals) {
-    // Both first-look and seen summaries go into the minimize mutation; first-look bodies are
-    // rendered in the output so the agent sees them before the minimize happens.
+    // 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).
+    // First-look bodies are rendered so the agent sees them before the minimize happens.
     const minimizeIds = [...summaries.firstLook, ...summaries.seen].map((r) => r.id);
     if (minimizeApprovals) {
         for (const r of approvals)
             minimizeIds.push(r.id);
-        return { minimizeIds, firstLookSummaries: summaries.firstLook, surfacedApprovals: [] };
+        return {
+            minimizeIds,
+            firstLookSummaries: summaries.firstLook,
+            editedSummaries: summaries.edited,
+            surfacedApprovals: [],
+        };
     }
-    return { minimizeIds, firstLookSummaries: summaries.firstLook, surfacedApprovals: approvals };
+    return {
+        minimizeIds,
+        firstLookSummaries: summaries.firstLook,
+        editedSummaries: summaries.edited,
+        surfacedApprovals: approvals,
+    };
 }
 export function buildResolveCommand(threads, allCommentIds, reviews, checks, prNumber) {
     const argv = ["npx", "pr-shepherd", "resolve", String(prNumber)];

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

@@ -6,7 +6,7 @@ import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun } from "./helpers.mjs";
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, surfacedApprovals, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const isNewSha = stored?.headSha !== headSha;
@@ -73,7 +73,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,
@@ -84,6 +84,7 @@ export async function handleFixCode(ctx) {
             actionableComments,
             reviewSummaryIds,
             firstLookSummaries,
+            editedSummaries,
             surfacedApprovals,
             checks,
             changesRequestedReviews,

package/bin/commands/iterate/index.mjs

@@ -91,7 +91,11 @@ export async function runIterate(opts) {
     }
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
-    const { minimizeIds: reviewSummaryIds, firstLookSummaries, surfacedApprovals, } = classifyReviewSummaries({ firstLook: report.firstLookSummaries, seen: report.reviewSummaries }, report.approvedReviews, config.iterate.minimizeApprovals);
+    const { minimizeIds: reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = classifyReviewSummaries({
+        firstLook: report.firstLookSummaries,
+        seen: report.reviewSummaries,
+        edited: report.editedSummaries,
+    }, report.approvedReviews, config.iterate.minimizeApprovals);
     const hasActionableWork = report.threads.actionable.length > 0 ||
         report.comments.actionable.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
@@ -111,6 +115,7 @@ export async function runIterate(opts) {
             repoName,
             reviewSummaryIds,
             firstLookSummaries,
+            editedSummaries,
             surfacedApprovals,
         });
     }

package/bin/commands/iterate/render.mjs

@@ -1,18 +1,7 @@
 /**
- * Render a resolve command as a shell snippet for the narrow placeholder-based
- * invocation used by iterate.
- *
- * This is not a general-purpose shell escaper. It only wraps
- * `$DISMISS_MESSAGE` and whitespace-bearing `rc.argv` entries in double quotes
- * so the surrounding command template can later substitute placeholder values.
- *
- * Callers must preserve that contract:
- * - placeholder substitution must replace the entire quoted token (for example,
- *   replace `"$DISMISS_MESSAGE"` as a whole, not text inside the quotes);
- * - `rc.argv` must not contain `"`, `$`, `` ` ``, or `\`, because this helper
- *   does not escape them and will throw if they are present;
- * - `$HEAD_SHA` must not appear in `rc.argv`; when `requiresHeadSha` is set it
- *   is appended separately below as the already-quoted token `"$HEAD_SHA"`.
+ * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE` and whitespace-bearing
+ * argv entries in double quotes for placeholder substitution. Throws if argv contains `"`, `$`,
+ * `` ` ``, or `\`. `$HEAD_SHA` is appended separately when `requiresHeadSha` is set.
  */
 export function renderResolveCommand(rc) {
     const needsQuoting = (arg) => {
@@ -29,7 +18,7 @@ export function renderResolveCommand(rc) {
     }
     return parts.join(" ");
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = []) {
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = []) {
     const instructions = [];
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions) {
@@ -80,6 +69,12 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (firstLookSummaries.length > 0) {
         instructions.push(`Review the bodies shown under \`## Review summaries (first look — to be minimized)\` — you are seeing these for the first time. Their IDs are already included in the \`resolve:\` command's \`--minimize-comment-ids\`; if any warrants a \`## Shepherd Journal\` entry, record it before running resolve.`);
     }
+    const editedTotal = editedSummaries.length +
+        firstLookThreads.filter((t) => t.edited).length +
+        firstLookComments.filter((c) => c.edited).length;
+    if (editedTotal > 0) {
+        instructions.push(`Items under \`## Review summaries (edited since first look)\` and any first-look bullet tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body. Do **not** include their IDs in \`--minimize-comment-ids\`, \`--resolve-thread-ids\`, or \`--dismiss-review-ids\` — they are already closed or minimized on GitHub.`);
+    }
     if (resolveCommand.hasMutations) {
         const substituteParts = [];
         if (resolveCommand.requiresHeadSha) {

package/bin/commands/resolve-instructions.mjs

@@ -23,6 +23,11 @@ export function buildFetchInstructions(prNumber, result) {
     if (firstLookTotal > 0) {
         instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
     }
+    const editedTotal = firstLookThreads.filter((t) => t.edited).length +
+        firstLookComments.filter((c) => c.edited).length;
+    if (editedTotal > 0) {
+        instructions.push(`First-look bullets tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body. Do **not** include their IDs in \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\` — they are already closed or minimized on GitHub.`);
+    }
     if (hasSuggestions) {
         instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\`, one thread at a time. On \`applied: true\` mark it Fixed — the CLI already resolved the thread, so exclude the ID from \`--resolve-thread-ids\`. On \`applied: false\` read \`reason\` and \`patch\`, then fall through to the manual fix step — do not retry the same command. Optionally pass \`--dry-run\` (omitting \`--message\`) if you want to inspect the unified diff before it mutates the working tree — the CLI validates with \`git apply --check\`, returns the patch and \`valid: true/false\`, and exits \`1\` on drift without committing or resolving the thread.`);
     }

package/bin/commands/resolve.mjs

@@ -5,32 +5,59 @@ import { autoResolveOutdated, applyResolveOptions } from "../comments/resolve.mj
 import { loadConfig } from "../config/load.mjs";
 import { extractSuggestion } from "../suggestions/extract.mjs";
 import { buildFetchInstructions } from "./resolve-instructions.mjs";
-import { loadSeenSet, markSeen } from "../state/seen-comments.mjs";
-/**
- * Fetch mode: auto-resolve outdated threads and return all active items for LLM triage.
- */
+import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
+/** Fetch mode: auto-resolve outdated threads and return all active items for LLM triage. */
 export async function runResolveFetch(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
         throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
     }
-    // Always bypass cache for resolve — we need fresh data before mutating.
     const { data } = await fetchPrBatch(prNumber, repo);
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const unresolvedThreads = data.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = data.comments.filter((c) => !c.isMinimized);
-    // First-look: collect items that would normally be hidden and check seen markers.
     const outdatedCandidates = data.reviewThreads.filter((t) => t.isOutdated);
     const resolvedCandidates = data.reviewThreads.filter((t) => t.isResolved && !t.isOutdated);
     const minimizedThreadCandidates = data.reviewThreads.filter((t) => t.isMinimized && !t.isResolved && !t.isOutdated);
     const minimizedCommentCandidates = data.comments.filter((c) => c.isMinimized);
-    const seenSet = await loadSeenSet(stateKey);
-    const unseenOutdated = outdatedCandidates.filter((t) => !seenSet.has(t.id));
-    const unseenResolved = resolvedCandidates.filter((t) => !seenSet.has(t.id));
-    const unseenMinimizedThreads = minimizedThreadCandidates.filter((t) => !seenSet.has(t.id));
-    const unseenMinimizedComments = minimizedCommentCandidates.filter((c) => !seenSet.has(c.id));
-    // Auto-resolve outdated (same as before — fires regardless of first-look status).
+    const seenMap = await loadSeenMap(stateKey);
+    const unseenOutdated = [];
+    const editedOutdated = [];
+    for (const t of outdatedCandidates) {
+        const cls = classifyItem(t.id, t.body, seenMap);
+        if (cls === "new")
+            unseenOutdated.push(t);
+        else if (cls === "edited")
+            editedOutdated.push(t);
+    }
+    const unseenResolved = [];
+    const editedResolved = [];
+    for (const t of resolvedCandidates) {
+        const cls = classifyItem(t.id, t.body, seenMap);
+        if (cls === "new")
+            unseenResolved.push(t);
+        else if (cls === "edited")
+            editedResolved.push(t);
+    }
+    const unseenMinimizedThreads = [];
+    const editedMinimizedThreads = [];
+    for (const t of minimizedThreadCandidates) {
+        const cls = classifyItem(t.id, t.body, seenMap);
+        if (cls === "new")
+            unseenMinimizedThreads.push(t);
+        else if (cls === "edited")
+            editedMinimizedThreads.push(t);
+    }
+    const unseenMinimizedComments = [];
+    const editedMinimizedComments = [];
+    for (const c of minimizedCommentCandidates) {
+        const cls = classifyItem(c.id, c.body, seenMap);
+        if (cls === "new")
+            unseenMinimizedComments.push(c);
+        else if (cls === "edited")
+            editedMinimizedComments.push(c);
+    }
     const outdated = getOutdatedThreads(unresolvedThreads);
     const autoResolvedIds = new Set();
     if (outdated.length > 0) {
@@ -56,17 +83,37 @@ export async function runResolveFetch(opts) {
             firstLookStatus: "outdated",
             autoResolved: autoResolvedIds.has(t.id),
         })),
+        ...editedOutdated.map((t) => ({
+            ...t,
+            firstLookStatus: "outdated",
+            autoResolved: autoResolvedIds.has(t.id),
+            edited: true,
+        })),
         ...unseenResolved.map((t) => ({ ...t, firstLookStatus: "resolved" })),
+        ...editedResolved.map((t) => ({
+            ...t,
+            firstLookStatus: "resolved",
+            edited: true,
+        })),
         ...unseenMinimizedThreads.map((t) => ({ ...t, firstLookStatus: "minimized" })),
+        ...editedMinimizedThreads.map((t) => ({
+            ...t,
+            firstLookStatus: "minimized",
+            edited: true,
+        })),
+    ];
+    const firstLookComments = [
+        ...unseenMinimizedComments.map((c) => ({ ...c, firstLookStatus: "minimized" })),
+        ...editedMinimizedComments.map((c) => ({
+            ...c,
+            firstLookStatus: "minimized",
+            edited: true,
+        })),
     ];
-    const firstLookComments = unseenMinimizedComments.map((c) => ({
-        ...c,
-        firstLookStatus: "minimized",
-    }));
-    // Mark first-look items as seen (best-effort — markSeen never throws).
+    // Mark new and edited items as seen (best-effort — markSeen never throws).
     await Promise.allSettled([
-        ...firstLookThreads.map((t) => markSeen(stateKey, t.id)),
-        ...firstLookComments.map((c) => markSeen(stateKey, c.id)),
+        ...firstLookThreads.map((t) => markSeen(stateKey, t.id, t.body)),
+        ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
     ]);
     const result = {
         prNumber,
@@ -80,9 +127,7 @@ export async function runResolveFetch(opts) {
     };
     return { ...result, instructions: buildFetchInstructions(prNumber, result) };
 }
-/**
- * Mutation mode: resolve/minimize/dismiss by ID.
- */
+/** Mutation mode: resolve/minimize/dismiss by ID. */
 export async function runResolveMutate(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());

package/bin/reporters/text.mjs

@@ -112,7 +112,8 @@ export function formatText(report) {
             lines.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
         for (const c of firstLookComments) {
-            lines.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
+            const editedSuffix = c.edited ? ", edited" : "";
+            lines.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
         }
         firstLookSection = lines.join("\n");
     }

package/bin/state/seen-comments.mjs

@@ -1,10 +1,32 @@
-import { readFile, writeFile, mkdir, access, readdir } from "node:fs/promises";
+import { readFile, writeFile, rename, unlink, mkdir, access, readdir } from "node:fs/promises";
 import { join, dirname } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
 import { SAFE_SEGMENT } from "../util/path-segment.mjs";
 import { resolveStateBase } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/** Compute a 16-hex-char SHA-256 prefix of a comment body. */
+export function hashBody(body) {
+    return createHash("sha256").update(body, "utf8").digest("hex").slice(0, 16);
+}
+/**
+ * Classify a candidate item against the seen map.
+ *
+ * - "new"       — no marker exists; surface the body and write the marker.
+ * - "edited"    — marker exists but stored hash differs from the current body;
+ *                 surface the updated body and update the marker hash.
+ * - "unchanged" — marker exists and hash matches (or marker has no hash, which
+ *                 is treated conservatively as unchanged).
+ */
+export function classifyItem(id, body, map) {
+    const m = map.get(id);
+    if (!m)
+        return "new";
+    if (typeof m.bodyHash === "string" && m.bodyHash !== hashBody(body))
+        return "edited";
+    return "unchanged";
+}
 /**
  * Read the seen/ directory once and return a Set of already-seen IDs.
  * Prefer this over repeated hasSeen() calls to avoid EMFILE on large PRs.
@@ -20,6 +42,32 @@ export async function loadSeenSet(key) {
         return new Set();
     }
 }
+/**
+ * Read the seen/ directory and return a Map from ID to SeenMarker.
+ * Used when the caller needs the stored bodyHash to detect in-place edits.
+ * Returns an empty Map if the directory does not yet exist.
+ */
+export async function loadSeenMap(key) {
+    const map = new Map();
+    try {
+        const dir = resolveDir(key);
+        const entries = await readdir(dir);
+        const ids = entries.filter((e) => e.endsWith(".json")).map((e) => e.slice(0, -5));
+        for (const id of ids) {
+            try {
+                const raw = await readFile(join(dir, `${id}.json`), "utf8");
+                map.set(id, JSON.parse(raw));
+            }
+            catch {
+                // unreadable or malformed — skip
+            }
+        }
+    }
+    catch {
+        // directory doesn't exist or unreadable — return empty map
+    }
+    return map;
+}
 /** Return true if a "seen" marker exists for this id. */
 export async function hasSeen(key, id) {
     try {
@@ -30,17 +78,50 @@ export async function hasSeen(key, id) {
         return false;
     }
 }
-/** Write a "seen" marker for this id. Idempotent — preserves original seenAt on double-write. */
-export async function markSeen(key, id) {
+/**
+ * Write (or update) a "seen" marker for this id, storing the body hash so
+ * in-place edits can be detected on future fetches.
+ *
+ * - First call (no existing marker): creates `{ seenAt: now, bodyHash }`.
+ * - Subsequent call, hash unchanged: no-op (skips the write).
+ * - Subsequent call, hash changed: updates `bodyHash`, preserves original `seenAt`.
+ *
+ * All errors are silently swallowed — the marker is best-effort.
+ */
+export async function markSeen(key, id, body) {
+    let tmp;
     try {
         const path = resolvePath(key, id);
         await mkdir(dirname(path), { recursive: true });
-        // O_EXCL: create-only — EEXIST means already marked, which is the idempotent success case.
-        // seenAt is unix milliseconds (Date.now()), matching JS convention for this module.
-        await writeFile(path, JSON.stringify({ seenAt: Date.now() }), { flag: "wx", encoding: "utf8" });
+        const newHash = hashBody(body);
+        let existing = null;
+        try {
+            const raw = await readFile(path, "utf8");
+            existing = JSON.parse(raw);
+        }
+        catch {
+            // no existing marker — will create below
+        }
+        if (existing !== null && existing.bodyHash === newHash)
+            return;
+        const seenAt = existing?.seenAt ?? Date.now();
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await writeFile(tmp, JSON.stringify({ seenAt, bodyHash: newHash }), "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
     }
     catch {
-        // EEXIST = already seen. All other errors are best-effort.
+        // best-effort
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
     }
 }
 /** Read the full marker for inspection (returns null on miss or error). */

package/package.json

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