pr-shepherd 0.22.0 → 0.24.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -1,28 +1,24 @@
 # pr-shepherd
 
 Autonomous PR CI monitor and review-comment resolver for agentic coding tools, including Claude Code and Codex.
-The goal is to have an agent take a plan to a human-reviewable PR autonomously.
 
-Example Workflow:
+The goal is to help an agent carry a planned change to a human-reviewable PR: passing CI, no unresolved Shepherd-visible work, and a useful PR description/journal.
 
-1. `/model opusplan`
-2. Create a plan
-3. Accept the plan
-4. Switch to Auto Mode
-5. Prompt: `make a PR, then run /pr-shepherd:pr-shepherd`
-6. Agent makes a draft PR
-7. PR has passing CI -> draft is marked Ready for Review
-8. Review bots begin providing reviews
-9. Agent automatically classifies and fixes review comments based on the Plan
-10. Human reviews PR with a well-documented PR title and description, passing CI, and no open threads/comments/reviews
+## How It Works
 
-## How it works
+`pr-shepherd` moves deterministic PR orchestration into a CLI. The CLI fetches GitHub state, emits raw-enough context, and prints a numbered `## Instructions` section for the calling agent to follow. The agent still decides whether a comment or CI failure requires a code change.
 
-`pr-shepherd` optimizes token management, rate limits, and agentic orchestration by moving **ALL** deterministic logic and prompts to code via a CLI tool, enshrining what would be a large skill or command prompt (of which the agent would inevitably make mistakes) into the code and returning a clear, actionable prompt.
+The shipped skills invoke the default poll dispatcher (`pr-shepherd <PR>`, equivalent to `pr-shepherd poll <PR>`). Use `pr-shepherd iterate <PR>` for one single tick.
 
-The CLI emits unified recheck instructions. Generated commands call `pr-shepherd` directly.
+Each tick returns exactly one action:
 
-At a high level, the skill invokes `pr-shepherd <PR>` (which polls by default), providing actionable feedback directly to the agent:
+- `WAIT` — no immediate action; poll can recheck until timeout.
+- `MARK_READY` — the CLI already converted an eligible draft PR to ready for review.
+- `FIX_CODE` — review items, failing CI, conflicts, or minimization work need agent action.
+- `CANCEL` — terminal success for merged/closed PRs or elapsed ready-delay.
+- `ESCALATE` — manual direction is needed.
+
+Example shape:
 
 ```text
 > pr-shepherd 123
@@ -36,205 +32,171 @@ At a high level, the skill invokes `pr-shepherd <PR>` (which polls by default),
 
 ### `threadId=PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice)
 
-#### `commentId=PRRC_kwDOSGizTs58XB1M` (@alice)
-
 > The variable name is misleading.
->
-> Consider renaming `x` to `remainingSeconds` so readers don't have to
-> trace back to the declaration to understand its meaning.
 
 ## Failing checks
 
-- `24697658766` — `CI › lint / typecheck / test (22.x)`
+- `24697658766` — `CI › lint / typecheck / test (22.x)` [conclusion: FAILURE]
   > oxfmt
 
 ## Post-fix push
 
 - base: `main`
-- resolve: `pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
+- resolve: `pr-shepherd resolve 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
 
 ## Instructions
 
-_(schematic — actual steps depend on PR state)_
-
-1. Apply code fixes for each file referenced under `## Review threads`.
-2. For each failing check: examine the log tail to decide — rerun if transient, fix code if real.
-3. Commit changed files.
-4. Rebase and push: `git fetch origin && git rebase origin/main && git push --force-with-lease` — capture `HEAD_SHA=$(git rev-parse HEAD)`.
-5. Run the `resolve:` command above, substituting `"$HEAD_SHA"`.
-6. Add or update a `## Shepherd Journal` section in the PR description for any large decisions made, appending under the existing heading if it already exists.
-7. CI needs time to run on the new push. Run `pr-shepherd 123` again to continue until Shepherd returns `[CANCEL]` or `[ESCALATE]`.
+1. Decide for each item under `## Review threads` and `## Failing checks` whether a code change is warranted. If code changes are needed, apply edits, commit, rebase/push according to the repository's conventions, then run the `resolve:` command.
+2. For each failing check under `## Failing checks`: fetch logs when needed and decide whether to rerun or fix.
+3. Run the `resolve:` command shown above with a specific `$DISMISS_MESSAGE` and the relevant `$HEAD_SHA`.
+4. Stop this iteration.
 ```
 
-On every iteration, a command is returned to instruct the agent exactly what to do. No guessing, no thinking, as few agentic turns as possible:
+See [docs/actions.md](docs/actions.md) for the complete output contract.
 
-```text
-pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"
-```
+## Workflow Assumptions
 
-## Workflow
+This system is opinionated and works best with PRs that use required status checks and conversation resolution.
 
-This system makes opinionated decisions, which may or may not work for your team's workflow.
+- Human-authored threads are replied to, not resolved or minimized by Shepherd.
+- Detected bots and configured `botUsernames` review threads are returned until resolved; bot/non-human threads, PR comments, and review summaries can be resolved or minimized when eligible. Review summaries are not minimized while known inline child threads from that review remain unresolved.
+- Agents must not reply to their own latest thread reply; generated instructions call this out before `--reply-thread-ids` mutations.
+- Every review thread/comment/review summary is surfaced at least once, even if already outdated, resolved, or minimized; edited items re-surface through seen markers.
+- Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
+- The CLI never performs git mutations. It emits instructions; the caller commits, rebases, pushes, and handles repository hooks.
+- `commit-suggestion` turns one GitHub suggestion thread into a patch and commit instructions, but still does not edit the working tree or git history.
 
-- The following PR branch protection rules are expected:
-  - There are required status checks
-  - All inline comments are resolved
-- **ALL** comments/threads/reviews will be hidden by default except for PR approvals. The only option here is to hide PR approvals as well.
-  - The primary reason is to optimize tokens by avoiding re-fetching comments and re-adding them to the agent's context.
-  - This also ties hand-in-hand with requiring all inline comments to be resolved.
-  - We also want to avoid storing state as comments can be unresolved/minimized/hidden.
-- `pr-shepherd` keeps the PR title and description up to date, including a journal of decisions with links to comments/threads/reviews (that would be hidden at this point).
-  - This may break your workflow if your PR titles and descriptions are restricted to a specific format.
-- `pr-shepherd` does **NOT** reply to inline comments when resolving them. Doing so would require agentic loops and more tokens. Instead, it updates the PR title & description once per loop with only the relevant information.
-- Branches are currently kept up-to-date with `git push --force-with-lease`. Please make a PR for making `merge <default branch>` an option.
-- Branches are currently only rebased when 1) pushing a commit on a branch that is out of date or 2) there are merge conflicts. It does not continuously rebase the branch (use a merge queue for that).
-- To optimize AI code reviewer tokens, create your pull requests initially as drafts and instruct your AI code reviewers to only code review PRs that are ready for review. `pr-shepherd` will automatically mark PRs as ready for review when all CI passes (can be disabled). If you have no intention of marking your PR as ready for review, then don't run `pr-shepherd`.
+## Usage
 
-Some other workflow improvements:
+### Iterate A PR
 
-- `pr-shepherd` knows whether a GitHub Copilot code review is in progress
-- `pr-shepherd` waits 10 minutes (configurable) until after all comments are hidden and CI passes before exiting. The primary reason is to wait for any lingering automated code reviews that do not provide status updates via the GitHub GraphQL API.
-- The agent is instructed to cancel failed CI runs and, when a failure looks transient (e.g. network timeout, runner setup crash), re-run them via `gh run rerun <id> --failed`. The primary reason is to minimize CI costs.
-- `pr-shepherd` supports "commit suggestions" by converting them into a diff, applying them, and then committing them with attribution. This avoids a file read & write. One commit is always made per suggestion to avoid any merge conflicts — in these cases, the agent will resolve the comment manually.
+Claude Code:
 
-Recommendations:
+```text
+/goal /pr-shepherd:pr-shepherd        # infer PR from current branch
+/goal /pr-shepherd:pr-shepherd 42
+```
 
-- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. Keep an active goal cycling `pr-shepherd <PR>` until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures or CI that never starts).
-- 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.
+Codex:
 
-## Design Principles
+```text
+/goal $pr-shepherd        # infer PR from current branch
+/goal $pr-shepherd 42
+```
 
-- **Reduced agent context and turns** — logic lives in the CLI, not the prompt. The relevant context is provided automatically to the agent, reducing tool calls.
-- **Reduced GitHub rate-limit exposure** — GraphQL requests are batched when possible
-- **Minimal state** — `pr-shepherd` stores minimal state in `$PR_SHEPHERD_STATE_DIR` (default `$TMPDIR/pr-shepherd-state/`), not in the repository
-- **Classifications and decisions still happen at the agent level** — `pr-shepherd`'s goal is to provide sufficient context to make informed decisions and provide clear actionable steps without writing unreliable code-level heuristics
-- **Configurable** — `pr-shepherd` is configurable via `.pr-shepherdrc.yml`, which is only possible with a light prompt that simply invokes the CLI which returns the prompt.
+Direct CLI:
 
-## Usage
+```sh
+pr-shepherd 42                         # poll until non-WAIT or timeout
+pr-shepherd 42 --interval 45s --timeout 4m
+pr-shepherd 42 --ready-delay 15m
+pr-shepherd iterate 42                 # single tick
+pr-shepherd poll 42                    # explicit poll command
+```
 
-### Iterate a PR to completion
+### Resolve Review Items
 
-Poll dispatcher — checks CI and review comments, fixes issues, and marks the PR ready for review when clean. Each non-terminal tick emits an `## Instructions` section; the skill follows it, then invokes `pr-shepherd <PR>` again until `[CANCEL]` or `[ESCALATE]`.
+```sh
+pr-shepherd resolve 42 --fetch
+pr-shepherd resolve 42 --reply-thread-ids PRRT_abc --message "Renamed the variable for clarity." --require-sha "$(git rev-parse HEAD)"
+```
 
-Claude Code (via `pr-shepherd` skill):
+### Apply One Suggestion Thread
 
-```
-/pr-shepherd:pr-shepherd                  # infer PR from current branch
-/pr-shepherd:pr-shepherd 42
-/pr-shepherd:pr-shepherd 42 --ready-delay 15m
+```sh
+pr-shepherd commit-suggestion 42 --thread-id PRRT_abc --message "rename value for clarity"
 ```
 
-Codex or direct CLI:
+The output contains a diff and numbered instructions for applying, staging, committing, resolving, and pushing.
+
+### Mark Files As Viewed
 
 ```sh
-pr-shepherd 42
-pr-shepherd 42 --interval 45s --timeout 4m
-pr-shepherd 42 --ready-delay 15m
-pr-shepherd iterate 42               # single tick
+pr-shepherd mark-files-as-viewed 42 --tests
+pr-shepherd mark-files-as-viewed 42 src/a.ts --match '^docs/'
 ```
 
-## Iterate decision loop
+The shipped `mark-files-as-viewed` skill maps a standalone `tests` argument to `--tests`.
 
-On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, or `wait`). See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
+### Clean Local State
 
-## Cleaning state
-
-`pr-shepherd` accumulates state under `$PR_SHEPHERD_STATE_DIR` (seen markers, fix-attempt counters, stall fingerprints, etc.). To reset it:
+`pr-shepherd` stores seen markers, fix-attempt counters, stall fingerprints, ready-delay markers, and logs under `$PR_SHEPHERD_STATE_DIR` (default `$TMPDIR/pr-shepherd-state`).
 
 ```sh
-pr-shepherd clean current    # remove state for the current branch's PR
-pr-shepherd clean repo       # remove all state for this repo
-pr-shepherd clean all        # remove all pr-shepherd state
+pr-shepherd clean current
+pr-shepherd clean repo
+pr-shepherd clean all --dry-run
+pr-shepherd log-file
 ```
 
-Add `--dry-run` to preview what would be removed. See [docs/cli-usage.md](docs/cli-usage.md) for the full `clean` reference.
-
 ## Install
 
-> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. Ensure `pr-shepherd` is available on `PATH` wherever the skill runs.
+Skill and plugin install methods add the skill definitions only. Install the `pr-shepherd` CLI separately wherever the skill runs.
 
 ### Claude Code
 
-Install as a Claude Code plugin:
-
 ```bash
 claude /plugin marketplace add jonathanong/pr-shepherd
 claude /plugin install pr-shepherd
 ```
 
-This repo ships two `marketplace.json` files that serve different Claude install flows: the root `marketplace.json` resolves the published plugin (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
-
 ### Codex
 
-Codex uses the repo-shipped Codex plugin rather than the Claude plugin or `/pr-shepherd:*` slash commands. The plugin provides one `pr-shepherd` skill for iterating a PR to completion.
-
-Install the Codex plugin marketplace from GitHub:
-
 ```bash
 codex plugin marketplace add jonathanong/pr-shepherd
 ```
 
-Or pin a branch/tag/ref:
+Or pin a ref:
 
 ```bash
 codex plugin marketplace add jonathanong/pr-shepherd --ref main
 ```
 
-For local development, point Codex at a checkout:
+For local development:
 
 ```bash
 git clone https://github.com/jonathanong/pr-shepherd ~/.codex/plugin-sources/pr-shepherd
 codex plugin marketplace add ~/.codex/plugin-sources/pr-shepherd
 ```
 
-After adding the marketplace, open the Codex plugin directory, choose the `jonathanong` marketplace, and install/enable `pr-shepherd`. The marketplace root must contain `.agents/plugins/marketplace.json` and `plugins/pr-shepherd/`.
-
-Install the CLI where Codex will run it so `pr-shepherd` is available on `PATH`. The plugin only installs the skill; it does not install the CLI into target repositories.
-
-Iterate a PR from Codex:
-
-```bash
-pr-shepherd iterate 42
-```
-
-Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. Continue until Shepherd emits `[CANCEL]` or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures or CI that never starts). `pr-shepherd iterate 42` remains supported for existing workflows.
+After adding the marketplace, install/enable the `pr-shepherd` plugin from Codex. The marketplace root must contain `.agents/plugins/marketplace.json` and `plugins/pr-shepherd/`.
 
 ## Configuration
 
-Create a `.pr-shepherdrc.yml` in your project root (or any parent directory) to override defaults. The loader walks up from `cwd` to `$HOME` (if `$HOME` is on that path) or the filesystem root; the first match wins.
+Create `.pr-shepherdrc.yml` in your project root or an ancestor directory.
 
 ```yaml
 iterate:
-  fixAttemptsPerThread: 5 # raise before escalating to manual review
+  fixAttemptsPerThread: 5
+  stallTimeoutMinutes: 60
+  minimizeApprovals: false
   minimizeComments: all # all | bots | users | none
 checks:
   ciTriggerEvents:
     - pull_request
     - pull_request_target
-    - merge_group # add for merge-queue repos
+    - merge_group
 actions:
-  autoMarkReady: false # disable to stay draft until you manually promote
+  autoMarkReady: false
 ```
 
-Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`, then `GITHUB_PERSONAL_ACCESS_TOKEN`), `PR_SHEPHERD_STATE_DIR` (override loop-state and log base dir), `PR_SHEPHERD_LOG_DISABLED=1` (disable the per-worktree debug log).
+Environment variables:
+
+- `GH_TOKEN` / `GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN` for auth; `gh auth token` is used as a fallback.
+- `PR_SHEPHERD_STATE_DIR` to override state and log location.
+- `PR_SHEPHERD_LOG_DISABLED=1` to disable per-worktree debug logging.
 
-See [docs/configuration.md](docs/configuration.md) for full semantics and deprecated-key migration.
+See [docs/configuration.md](docs/configuration.md) for the full reference.
 
 ## Requirements
 
-- Node.js ≥ 22.0.0
-- A GitHub token: set `GH_TOKEN` or `GITHUB_TOKEN`, **or** install and authenticate the `gh` CLI (`gh auth login`) — pr-shepherd uses `gh auth token` as a fallback before trying `GITHUB_PERSONAL_ACCESS_TOKEN`. The `repo` scope is required for private repositories.
+- Node.js >= 22.0.0
+- A GitHub token or authenticated `gh` CLI; private repositories require `repo` scope.
 - `git`
 
 ## Docs
 
-Full reference: [docs/README.md](docs/README.md) — CLI usage, skills, configuration, architecture, actions, debugging, and more.
-
-## Architecture
-
-See [docs/architecture.md](docs/architecture.md) for the module map and dependency rules.
+Full reference: [docs/README.md](docs/README.md).
 
 ## License
 

package/bin/cli/args.mjs

@@ -13,10 +13,12 @@ const FLAGS_WITH_VALUES = new Set([
     "--description",
     "--thread-id",
     "--resolve-thread-ids",
+    "--reply-thread-ids",
     "--minimize-comment-ids",
     "--dismiss-review-ids",
     "--interval",
     "--timeout",
+    "--match",
 ]);
 // Boolean flags that do NOT consume the next argument. Any --flag not in this
 // set and not in FLAGS_WITH_VALUES is treated conservatively as value-taking

package/bin/cli/fix-formatter.mjs

@@ -12,8 +12,10 @@ export function formatFixCodeResult(header, result, opts) {
             const lineLabel = renderLineRange(t.startLine, t.line);
             const loc = t.path ? `\`${t.path}:${lineLabel}\`` : "(no location)";
             const heading = t.url ? `[threadId=${t.id}](${t.url})` : `\`threadId=${t.id}\``;
+            const reviewMarker = t.reviewId ? ` [reviewId=${t.reviewId}]` : "";
             const suggestionMarker = t.suggestion ? " [suggestion]" : "";
-            sections.push(`### ${heading} — ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}`);
+            const editedMarker = t.edited ? " [edited since first look]" : "";
+            sections.push(`### ${heading} — ${loc} (${renderAuthor(t.author, t.authorType)})${reviewMarker}${suggestionMarker}${editedMarker}`);
             sections.push(renderThreadConversation(t));
             if (t.suggestion) {
                 sections.push(renderSuggestionBlock(t.suggestion, ""));

package/bin/cli/formatters.mjs

@@ -1,6 +1,8 @@
 export { formatIterateResult } from "./iterate-formatter.mjs";
 export { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mjs";
 export { formatCleanResult } from "./clean-formatter.mjs";
+export { formatMarkFilesAsViewedResult } from "./mark-files-as-viewed-formatter.mjs";
+export { formatMutateResult } from "./mutate-formatter.mjs";
 import { safeFence } from "./fence.mjs";
 import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderThreadResolutionStatusTag, buildFirstLookBullets, renderEditedCommentTag, } from "./list-formatters.mjs";
 import { joinSections } from "../util/markdown.mjs";
@@ -79,12 +81,7 @@ export function formatCommitSuggestionResult(result) {
         lines.push(result.patch.trimEnd());
         lines.push(fence);
     }
-    lines.push("");
-    lines.push("## Suggested commit message");
-    lines.push("");
-    lines.push(result.commitMessage);
-    lines.push("");
-    lines.push(result.commitBody);
+    lines.push("", "## Suggested commit message", "", result.commitMessage, "", result.commitBody);
     if (result.postActionInstructions.length > 0) {
         lines.push("");
         lines.push("## Instructions");
@@ -95,42 +92,3 @@ export function formatCommitSuggestionResult(result) {
     }
     return lines.join("\n");
 }
-export function formatMutateResult(result) {
-    const lines = [];
-    if (result.resolvedThreads.length)
-        lines.push(`Resolved threads (${result.resolvedThreads.length}): ${result.resolvedThreads.join(", ")}`);
-    if (result.minimizedComments.length)
-        lines.push(`Minimized comments (${result.minimizedComments.length}): ${result.minimizedComments.join(", ")}`);
-    if (result.dismissedReviews.length)
-        lines.push(`Dismissed reviews (${result.dismissedReviews.length}): ${result.dismissedReviews.join(", ")}`);
-    if (result.skippedDismissals?.length)
-        lines.push(`Skipped dismissals (${result.skippedDismissals.length}): ${result.skippedDismissals.join(", ")}`);
-    if (result.rateLimit) {
-        const details = [
-            result.rateLimit.retryAfterSeconds !== undefined
-                ? `retry after ${result.rateLimit.retryAfterSeconds}s`
-                : null,
-            result.rateLimit.remaining !== undefined && result.rateLimit.limit !== undefined
-                ? `remaining ${result.rateLimit.remaining}/${result.rateLimit.limit}`
-                : null,
-            result.rateLimit.resetAt !== undefined
-                ? `reset at ${new Date(result.rateLimit.resetAt * 1000).toISOString()}`
-                : null,
-        ]
-            .filter(Boolean)
-            .join(", ");
-        lines.push(`Stopped: GitHub rate limit hit — ${result.rateLimit.message}${details ? ` (${details})` : ""}`);
-    }
-    if (result.unresolvedThreads?.length)
-        lines.push(`Not resolved due to rate limit (${result.unresolvedThreads.length}): ${result.unresolvedThreads.join(", ")}`);
-    if (result.unminimizedComments?.length)
-        lines.push(`Not minimized due to rate limit (${result.unminimizedComments.length}): ${result.unminimizedComments.join(", ")}`);
-    if (result.undismissedReviews?.length)
-        lines.push(`Not dismissed due to rate limit (${result.undismissedReviews.length}): ${result.undismissedReviews.join(", ")}`);
-    const errors = result.rateLimit
-        ? result.errors.filter((e) => !e.startsWith("rate limit:"))
-        : result.errors;
-    if (errors.length)
-        lines.push(`Errors:\n  ${errors.join("\n  ")}`);
-    return lines.join("\n");
-}

package/bin/cli/handlers.mjs

@@ -1,12 +1,14 @@
 import { runCommitSuggestion } from "../commands/commit-suggestion.mjs";
+import { runMarkFilesAsViewed } from "../commands/mark-files-as-viewed.mjs";
 import { runIterate } from "../commands/iterate/index.mjs";
 import { runClean } from "../commands/clean.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { parseCommonArgs, getFlag } from "./args.mjs";
 import { USAGE } from "./help.mjs";
-import { formatCommitSuggestionResult, formatCleanResult } from "./formatters.mjs";
+import { formatCommitSuggestionResult, formatCleanResult, formatMarkFilesAsViewedResult, } from "./formatters.mjs";
 import { parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
+import { parseMarkFilesAsViewedArgs } from "./mark-files-as-viewed-flags.mjs";
 const CLEAN_VARIANTS = new Set(["pr", "branch", "current", "repo", "all"]);
 export async function handleClean(args) {
     const variant = args[0];
@@ -108,3 +110,22 @@ export async function handleIterate(args) {
         readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
     });
 }
+export async function handleMarkFilesAsViewed(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const parsed = parseMarkFilesAsViewedArgs(extra);
+    if (!parsed.ok) {
+        process.stderr.write(`pr-shepherd: mark-files-as-viewed: ${parsed.error}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const result = await runMarkFilesAsViewed({
+        ...globalOpts,
+        prNumber,
+        files: parsed.files,
+        tests: parsed.tests,
+        matchPatterns: parsed.matchPatterns,
+    });
+    process.stdout.write(globalOpts.format === "json"
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : `${formatMarkFilesAsViewedResult(result)}\n`);
+}

package/bin/cli/help-command-pages.mjs

@@ -5,6 +5,7 @@ Fetch actionable review items or apply GitHub review-state mutations after fixes
 
 Usage:
   pr-shepherd resolve [PR] [--fetch] [--format text|json]
+  pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
   pr-shepherd resolve [PR] --resolve-thread-ids A,B [--minimize-comment-ids X,Y]
                             [--dismiss-review-ids Q] [--message MSG]
                             [--require-sha SHA] [--format text|json]
@@ -13,14 +14,18 @@ Modes:
   fetch                Default when no mutation IDs are provided. Fetches review threads,
                        comments, first-look items, and instructions.
   mutate               Runs when any mutation ID flag is present. Resolves threads,
-                       minimizes comments/review summaries, and dismisses reviews.
+                       replies to human threads, resolves non-human/manual thread IDs,
+                       minimizes non-human comments/review summaries, and dismisses non-human reviews.
 
 Flags:
   --fetch                         Force fetch mode.
   --resolve-thread-ids <ids>      Comma-separated review thread IDs to resolve.
+                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
+  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
   --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
-  --message <text>                Dismiss message. Required with --dismiss-review-ids.
+  --message <text>                Reply/dismiss message. Required with --reply-thread-ids
+                                  or --dismiss-review-ids.
   --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.
   --format text|json              Output format. Default: text.
   --help, -h                      Print this help and exit before GitHub I/O.
@@ -49,6 +54,26 @@ Preconditions:
 Exit codes:
   0  suggestion patch and instructions produced
   1  validation, lookup, precondition, or suggestion parsing failure`,
+    "mark-files-as-viewed": `pr-shepherd mark-files-as-viewed
+
+Mark changed files as viewed in the GitHub pull request diff.
+
+Usage:
+  pr-shepherd mark-files-as-viewed [PR] [files...] [--tests] [--match REGEX]
+                                      [--format text|json]
+
+Selectors:
+  files...          Exact changed-file paths from the PR diff.
+  --tests           Select changed test files.
+  --match <regex>   Select changed files whose paths match a case-insensitive JavaScript regex.
+                    May be repeated.
+
+Flags:
+  --format text|json  Output format. Default: text.
+  --help, -h          Print this help and exit before GitHub I/O.
+
+PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
+Exit code: 0 on success; 1 on validation or lookup failure.`,
     iterate: `pr-shepherd iterate
 
 Run one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.

package/bin/cli/help-top-page.mjs

@@ -10,6 +10,7 @@ Usage:
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
   pr-shepherd resolve [PR] [resolve-flags]
   pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [flags]
+  pr-shepherd mark-files-as-viewed [PR] [files...] [--tests] [--match REGEX]
   pr-shepherd clean <pr|branch|current|repo|all> [value] [flags]
   pr-shepherd log-file [--format text|json]
 
@@ -19,6 +20,7 @@ Commands:
   poll                 Re-run iterate while the action is WAIT, then print the final tick.
   resolve              Fetch actionable review items, or resolve/minimize/dismiss IDs.
   commit-suggestion    Convert one GitHub suggestion thread into a patch and commit instructions.
+  mark-files-as-viewed Mark PR changed files as viewed in GitHub.
   clean                Remove pr-shepherd state files.
   log-file             Print the per-worktree debug log path.
 

package/bin/cli/iterate-instructions.mjs

@@ -32,7 +32,7 @@ export function adaptFixCodeInstructions(instructions, pr, readyDelaySuffix) {
 export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }
-export function buildIterateCommand(pr, readyDelaySuffix) {
+function buildIterateCommand(pr, readyDelaySuffix) {
     const suffix = readyDelaySuffix?.trim();
     return buildPrShepherdCommand([String(pr), ...(suffix ? ["--ready-delay", suffix] : [])]).text;
 }

package/bin/cli/list-formatters.mjs

@@ -9,7 +9,7 @@ export function renderBodyPreview(body) {
     const firstLine = normalizedBody.split("\n")[0]?.trim() ?? "";
     return firstLine.slice(0, BODY_PREVIEW_MAX);
 }
-export function renderFirstLookStatusTag(t) {
+function renderFirstLookStatusTag(t) {
     const editedSuffix = t.edited ? ", edited" : "";
     return t.autoResolved
         ? `[status: outdated, auto-resolved${editedSuffix}]`
@@ -27,8 +27,10 @@ export function renderThreadBullet(t, opts = {}) {
         ? `\`${t.path}:${renderLineRange(t.startLine ?? undefined, t.line ?? null)}\``
         : "`(no location)`";
     const suggestionMarker = t.suggestion ? " [suggestion]" : "";
+    const editedMarker = t.edited && !opts.suppressEditedMarker ? " [edited since first look]" : "";
+    const reviewMarker = t.reviewId ? ` [reviewId=${t.reviewId}]` : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}${statusSuffix}`;
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
     if (!opts.noBody && (!t.comments || t.comments.length === 0)) {
         const legacyLine = `${bulletLine}: ${renderBodyPreview(t.body)}`;
         return t.suggestion && opts.renderSuggestion
@@ -111,6 +113,7 @@ export function buildFirstLookBullets(firstLookThreads, resolutionOnlyIds, first
         bullets.push(renderThreadBullet(t, {
             statusTag: renderFirstLookStatusTag(t),
             noBody: resolutionOnlyIds.has(t.id),
+            suppressEditedMarker: true,
         }));
     }
     for (const c of firstLookComments) {

package/bin/cli/mark-files-as-viewed-flags.mjs

@@ -0,0 +1,34 @@
+import { hasFlag } from "./args.mjs";
+export function parseMarkFilesAsViewedArgs(args) {
+    const files = [];
+    const matchPatterns = [];
+    const tests = hasFlag(args, "--tests");
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--tests")
+            continue;
+        if (arg === "--match") {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { ok: false, error: "--match requires a regex value" };
+            }
+            matchPatterns.push(value);
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--match=")) {
+            const value = arg.slice("--match=".length);
+            if (value === "")
+                return { ok: false, error: "--match requires a regex value" };
+            matchPatterns.push(value);
+            continue;
+        }
+        if (arg.startsWith("--"))
+            return { ok: false, error: `unknown flag: "${arg}"` };
+        files.push(arg);
+    }
+    if (files.length === 0 && !tests && matchPatterns.length === 0) {
+        return { ok: false, error: "provide at least one file, --tests, or --match <regex>" };
+    }
+    return { ok: true, files, tests, matchPatterns };
+}