pr-shepherd 0.34.0 → 0.36.0

package/bin/checks/triage.mjs

@@ -1,5 +1,5 @@
 /* eslint-disable max-lines */
-import { rest, restText } from "../github/http.mjs";
+import { restWithRateLimit, restText } from "../github/http.mjs";
 const STARTUP_FAILURE_STATUS = "startup_failure";
 const LOG_EXCERPT_CONTEXT_LINES = 16;
 const LOG_EXCERPT_TAIL_LINES = 28;
@@ -43,10 +43,14 @@ async function fetchStartupFailureChecksUncached(repo, headSha, prNumber) {
     const MAX_RUN_PAGES = 10;
     const checks = [];
     for (let page = 1; page <= MAX_RUN_PAGES; page++) {
-        const data = await rest("GET", `/repos/${owner}/${name}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=${STARTUP_FAILURE_STATUS}&per_page=${perPage}&page=${page}`);
+        const { data, rateLimit } = await restWithRateLimit("GET", `/repos/${owner}/${name}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=${STARTUP_FAILURE_STATUS}&per_page=${perPage}&page=${page}`);
         checks.push(...data.workflow_runs
             .filter((run) => runBelongsToPr(run, prNumber, headSha))
             .map(workflowRunToCheckRun));
+        if (rateLimit?.remaining === 0) {
+            process.stderr.write(`pr-shepherd: REST rate limit remaining is 0 while listing startup-failure runs for ${headSha} — detection may be incomplete\n`);
+            break;
+        }
         if (data.workflow_runs.length < perPage)
             break;
         if (page === MAX_RUN_PAGES) {
@@ -91,8 +95,12 @@ async function fetchJobsUncached(runId, repo) {
                 process.stderr.write(`pr-shepherd: job pagination cap (${MAX_JOB_PAGES * 100} jobs) reached for run ${runId} — triage may be incomplete\n`);
                 break;
             }
-            const data = await rest("GET", `/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest&per_page=${perPage}&page=${page}`);
+            const { data, rateLimit } = await restWithRateLimit("GET", `/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest&per_page=${perPage}&page=${page}`);
             allJobs.push(...data.jobs);
+            if (rateLimit?.remaining === 0) {
+                process.stderr.write(`pr-shepherd: REST rate limit remaining is 0 while listing jobs for run ${runId} — triage may be incomplete\n`);
+                break;
+            }
             if (data.jobs.length < perPage)
                 break;
         }

package/bin/classify/apply.d.mts

@@ -0,0 +1,18 @@
+import type { BatchPrData } from "../types.mts";
+import type { LoadedRule } from "./loader.mts";
+export interface ClassifyIndex {
+    suppressedIds: Set<string>;
+    autoResolveIds: Set<string>;
+}
+export interface BatchPartition {
+    suppressedCommentIds: Set<string>;
+    suppressedThreadIds: Set<string>;
+    suppressedReviewSummaryIds: Set<string>;
+    suppressedChangesRequestedIds: Set<string>;
+    ruleAutoResolveCommentIds: string[];
+    ruleAutoResolveThreadIds: string[];
+    /** COMMENTED review summary IDs — minimized without surfacing to the agent. */
+    ruleAutoResolveReviewSummaryIds: string[];
+}
+export declare function buildClassifyIndex(rules: LoadedRule[], batch: BatchPrData): ClassifyIndex;
+export declare function partitionBatch(index: ClassifyIndex, batch: BatchPrData): BatchPartition;

package/bin/classify/apply.mjs

@@ -26,6 +26,7 @@ function threadToItem(t) {
         id: t.id,
         author: t.author,
         authorType: t.authorType,
+        ...(t.authorAssociation !== undefined && { authorAssociation: t.authorAssociation }),
         body: t.body,
         url: t.url,
         path: t.path,
@@ -37,6 +38,7 @@ function commentToItem(c) {
         id: c.id,
         author: c.author,
         authorType: c.authorType,
+        ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
         body: c.body,
         url: c.url,
     };
@@ -47,6 +49,7 @@ function reviewSummaryToItem(r) {
         id: r.id,
         author: r.author,
         authorType: r.authorType,
+        ...(r.authorAssociation !== undefined && { authorAssociation: r.authorAssociation }),
         body: r.body,
     };
 }
@@ -56,6 +59,7 @@ function changesRequestedToItem(r) {
         id: r.id,
         author: r.author,
         authorType: r.authorType,
+        ...(r.authorAssociation !== undefined && { authorAssociation: r.authorAssociation }),
         body: r.body,
     };
 }

package/bin/classify/loader.d.mts

@@ -0,0 +1,10 @@
+import type { ClassifyRule } from "./types.mts";
+export interface LoadedRule {
+    name: string;
+    file: string;
+    rule: ClassifyRule;
+}
+export declare function discoverRuleFiles(cwd: string): string[];
+export declare function loadRules(files: string[]): Promise<LoadedRule[]>;
+/** Reset the rule cache — for use in tests. */
+export declare function _resetRuleCache(): void;

package/bin/classify/types.d.mts

@@ -0,0 +1,35 @@
+/** Raw relationship between a comment author and the repository, as reported by GitHub. */
+export type CommentAuthorAssociation = "COLLABORATOR" | "CONTRIBUTOR" | "FIRST_TIMER" | "FIRST_TIME_CONTRIBUTOR" | "MANNEQUIN" | "MEMBER" | "NONE" | "OWNER";
+export type ClassifyItemKind = "review-thread" | "pr-comment" | "review-summary" | "changes-requested";
+export interface ClassifyItemBase {
+    readonly kind: ClassifyItemKind;
+    readonly id: string;
+    readonly author: string;
+    readonly authorType: "User" | "Bot" | "Unknown";
+    readonly authorAssociation?: CommentAuthorAssociation;
+    readonly body: string;
+    readonly url?: string;
+}
+export interface ClassifyReviewThread extends ClassifyItemBase {
+    readonly kind: "review-thread";
+    readonly path?: string | null;
+}
+export interface ClassifyPrComment extends ClassifyItemBase {
+    readonly kind: "pr-comment";
+}
+export interface ClassifyReviewSummary extends ClassifyItemBase {
+    readonly kind: "review-summary";
+}
+export interface ClassifyChangesRequested extends ClassifyItemBase {
+    readonly kind: "changes-requested";
+}
+export type ClassifyItem = ClassifyReviewThread | ClassifyPrComment | ClassifyReviewSummary | ClassifyChangesRequested;
+export interface ClassifyAction {
+    /** When true, routes the item's ID to the appropriate resolve/minimize GitHub mutation. Not supported for changes-requested reviews. */
+    readonly autoResolve?: boolean;
+    /** When true, hides the item from agent output (seen marker is still written). */
+    readonly suppress?: boolean;
+    /** Optional note recorded to the debug log when this rule fires. */
+    readonly reason?: string;
+}
+export type ClassifyRule = (item: ClassifyItem) => ClassifyAction | null | undefined;

package/bin/cli/args.d.mts

@@ -0,0 +1,18 @@
+/**
+ * CLI argument-parsing helpers extracted from cli.mts for testability.
+ */
+import type { GlobalOptions } from "../types.mts";
+export declare function parseIntStrict(value: string, flag: string): number;
+interface ParsedArgs {
+    prNumber: number | undefined;
+    global: GlobalOptions;
+    extra: string[];
+}
+export declare function parseCommonArgs(args: string[]): ParsedArgs;
+export declare function parsePrNumber(value: string): number | null;
+/** Get the value of a flag like `--flag value` or `--flag=value`. */
+export declare function getFlag(args: string[], name: string): string | null;
+export declare function hasFlag(args: string[], name: string): boolean;
+export declare function parseList(value: string | null): string[];
+export declare function parseStatusPrNumbers(args: string[]): number[];
+export {};

package/bin/cli/args.mjs

@@ -18,6 +18,7 @@ const FLAGS_WITH_VALUES = new Set([
     "--dismiss-review-ids",
     "--interval",
     "--timeout",
+    "--debounce",
     "--match",
 ]);
 // Boolean flags that do NOT consume the next argument. Any --flag not in this

package/bin/cli/clean-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { CleanResult } from "../commands/clean.mts";
+export declare function formatCleanResult(result: CleanResult): string;

package/bin/cli/default-poll.d.mts

@@ -0,0 +1,2 @@
+export declare function isDefaultPollInvocation(subcommand: string | undefined): boolean;
+export declare function validateDefaultPollArgs(args: string[]): boolean;

package/bin/cli/default-poll.mjs

@@ -8,6 +8,7 @@ const DEFAULT_POLL_FLAGS_WITH_VALUES = new Set([
     "--stall-timeout",
     "--interval",
     "--timeout",
+    "--debounce",
 ]);
 const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
     "--verbose",

package/bin/cli/duration-flag.d.mts

@@ -0,0 +1,2 @@
+import type { DurationParseOptions } from "./duration.mts";
+export declare function validateSecondsDurationFlag(command: string, flag: string, value: string | null, presentAsSeparateArg: boolean, opts?: DurationParseOptions): string | undefined | null;

package/bin/cli/duration.d.mts

@@ -0,0 +1,13 @@
+interface SecondsDurationParts {
+    value: number;
+    unit: string;
+}
+export interface DurationParseOptions {
+    /** Unit assumed for a bare number with no suffix. Defaults to seconds. */
+    defaultUnit?: "s" | "m";
+    /** When true, 0 is accepted (used by flags where 0 means "disabled"). */
+    allowZero?: boolean;
+}
+export declare function parseSecondsDurationParts(s: string, opts?: DurationParseOptions): SecondsDurationParts | null;
+export declare function parseDurationToSeconds(s: string, defaultSeconds: number, opts?: DurationParseOptions): number;
+export {};

package/bin/cli/fence.d.mts

@@ -0,0 +1 @@
+export declare function safeFence(content: string): string;

package/bin/cli/fix-formatter-extra.d.mts

@@ -0,0 +1,3 @@
+import type { CheckAnnotation, IterateResultFixCode } from "../types.mts";
+export declare function renderCheckAnnotation(a: CheckAnnotation): string;
+export declare function renderProtectedRun(run: IterateResultFixCode["fix"]["protectedRuns"][number]): string;

package/bin/cli/fix-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { IterateResultFixCode } from "../types.mts";
+export declare function formatFixCodeResult(header: string, result: IterateResultFixCode): string;

package/bin/cli/fix-formatter.mjs

@@ -15,7 +15,7 @@ export function formatFixCodeResult(header, result) {
             const reviewMarker = t.reviewId ? ` [reviewId=${t.reviewId}]` : "";
             const suggestionMarker = t.suggestion ? " [suggestion]" : "";
             const editedMarker = t.edited ? " [edited since first look]" : "";
-            sections.push(`### ${heading} — ${loc} (${renderAuthor(t.author, t.authorType)})${reviewMarker}${suggestionMarker}${editedMarker}`);
+            sections.push(`### ${heading} — ${loc} (${renderAuthor(t.author, t.authorType, t.authorAssociation)})${reviewMarker}${suggestionMarker}${editedMarker}`);
             sections.push(renderThreadConversation(t));
             if (t.suggestion) {
                 sections.push(renderSuggestionBlock(t.suggestion, ""));
@@ -33,7 +33,7 @@ export function formatFixCodeResult(header, result) {
         for (const c of result.fix.actionableComments) {
             const heading = c.url ? `[commentId=${c.id}](${c.url})` : `\`commentId=${c.id}\``;
             const editedMarker = c.edited ? " [edited since first look]" : "";
-            sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType)})${editedMarker}`);
+            sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${editedMarker}`);
             sections.push(blockquote(c.body));
         }
     }
@@ -83,14 +83,14 @@ export function formatFixCodeResult(header, result) {
     if (result.fix.firstLookSummaries.length > 0) {
         sections.push("## Review summaries (first look)");
         for (const r of result.fix.firstLookSummaries) {
-            sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})`);
+            sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})`);
             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}\` (${renderAuthor(r.author, r.authorType)})`);
+            sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})`);
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
         }
     }
@@ -103,7 +103,7 @@ export function formatFixCodeResult(header, result) {
     if (result.fix.surfacedApprovals.length > 0) {
         sections.push("## Approvals (surfaced — not minimized)");
         for (const r of result.fix.surfacedApprovals) {
-            sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})`);
+            sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})`);
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
         }
     }
@@ -129,7 +129,7 @@ export function formatFixCodeResult(header, result) {
     if (result.fix.resolveOnlyCommand?.hasMutations)
         postFixLines.push(`- resolve-only: \`${renderResolveCommand(result.fix.resolveOnlyCommand)}\``);
     if (result.fix.resolveCommand.hasMutations) {
-        postFixLines.push(`- resolve: \`${renderResolveCommand(result.fix.resolveCommand)}\``);
+        postFixLines.push(`- apply review: \`${renderResolveCommand(result.fix.resolveCommand)}\``);
     }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");

package/bin/cli/formatters.d.mts

@@ -0,0 +1,7 @@
+export { formatIterateResult } from "./iterate-formatter.mts";
+export { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mts";
+export { formatCleanResult } from "./clean-formatter.mts";
+export { formatMarkFilesAsViewedResult } from "./mark-files-as-viewed-formatter.mts";
+export { formatMutateResult } from "./mutate-formatter.mts";
+import type { CommitSuggestionResult } from "../types.mts";
+export declare function formatCommitSuggestionResult(result: CommitSuggestionResult): string;

package/bin/cli/handlers.d.mts

@@ -0,0 +1,4 @@
+export declare function handleClean(args: string[], command?: "admin clean" | "clean"): Promise<void>;
+export declare function handleCommitSuggestion(args: string[], command?: "build-suggestion-patch" | "commit-suggestion"): Promise<void>;
+export declare function handleIterate(args: string[]): Promise<void>;
+export declare function handleMarkFilesAsViewed(args: string[], command?: "apply files" | "mark-files-as-viewed"): Promise<void>;

package/bin/cli/handlers.mjs

@@ -11,10 +11,11 @@ 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) {
+export async function handleClean(args, command = "admin clean") {
+    const usage = command === "admin clean" ? USAGE["admin clean"] : USAGE.clean;
     const variant = args[0];
     if (!variant || !CLEAN_VARIANTS.has(variant)) {
-        process.stderr.write(`${USAGE.clean}\n`);
+        process.stderr.write(`${usage}\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -24,7 +25,7 @@ export async function handleClean(args) {
             continue;
         if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
             continue;
-        process.stderr.write(`pr-shepherd: clean: unknown flag: "${a}"\n`);
+        process.stderr.write(`pr-shepherd: ${command}: unknown flag: "${a}"\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -38,7 +39,7 @@ export async function handleClean(args) {
         formatValue = rest[fmtIdx + 1];
     }
     if (formatValue !== undefined && formatValue !== "text" && formatValue !== "json") {
-        process.stderr.write(`pr-shepherd: clean: invalid --format value: "${formatValue}". Expected "text" or "json".\n`);
+        process.stderr.write(`pr-shepherd: ${command}: invalid --format value: "${formatValue}". Expected "text" or "json".\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -52,24 +53,24 @@ export async function handleClean(args) {
     }
     const positionals = rest.filter((a, i) => !flagConsumedIndices.has(i) && !a.startsWith("--"));
     if (positionals.length > 1) {
-        process.stderr.write(`pr-shepherd: clean: too many positional arguments (expected at most 1, got ${positionals.length})\n`);
+        process.stderr.write(`pr-shepherd: ${command}: too many positional arguments (expected at most 1, got ${positionals.length})\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
     const value = positionals[0];
     const result = await runClean({ variant: variant, value, dryRun });
     if (!result.ok) {
-        process.stderr.write(`pr-shepherd: clean: ${result.error}\n`);
+        process.stderr.write(`pr-shepherd: ${command}: ${result.error}\n`);
         process.exitCode = EXIT.SOFTWARE;
         return;
     }
     process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${formatCleanResult(result)}\n`);
 }
-export async function handleCommitSuggestion(args) {
+export async function handleCommitSuggestion(args, command = "build-suggestion-patch") {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const threadId = getFlag(extra, "--thread-id");
     if (!threadId) {
-        process.stderr.write(`${USAGE["commit-suggestion"]}\n`);
+        process.stderr.write(`${USAGE[command]}\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -111,11 +112,11 @@ export async function handleIterate(args) {
         readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
     });
 }
-export async function handleMarkFilesAsViewed(args) {
+export async function handleMarkFilesAsViewed(args, command = "apply files") {
     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.stderr.write(`pr-shepherd: ${command}: ${parsed.error}\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }

package/bin/cli/help-command-pages.d.mts

@@ -0,0 +1,231 @@
+export declare const COMMAND_USAGE: {
+    readonly default: string;
+    readonly apply: `pr-shepherd apply
+
+Apply a review mutation, mark changed files as viewed, or append a PR journal item.
+
+Usage:
+  pr-shepherd apply review [PR] [review-flags]
+  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
+  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
+  pr-shepherd apply journal [PR] --file <path> [--dry-run] [--format text|json]
+
+Run 'pr-shepherd apply <review|files|journal> --help' for command-specific details.
+--help, -h                      Print this help and exit before GitHub I/O.`;
+    readonly "apply review": `pr-shepherd apply review
+
+Apply GitHub review-state mutations after fixes.
+
+Usage:
+  pr-shepherd apply review [PR] --reply-thread-ids A,B --message MSG
+  pr-shepherd apply review [PR] --resolve-thread-ids A,B [--minimize-comment-ids X,Y]
+                                  [--dismiss-review-ids Q] [--message MSG]
+                                  [--require-sha SHA] [--format text|json]
+
+Flags:
+  --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) 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>                Reply/dismiss message. Required with reply or dismiss IDs.
+  --require-sha <sha>             Wait for this full 40-character lowercase PR head SHA.
+  --format text|json              Output format. Default: text.
+
+At least one action flag is required.
+--help, -h                      Print this help and exit before GitHub I/O.`;
+    readonly "apply files": `pr-shepherd apply files
+
+Mark changed files as viewed in the GitHub pull request diff.
+
+Usage:
+  pr-shepherd apply files [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.
+--help, -h                      Print this help and exit before GitHub I/O.`;
+    readonly "apply journal": `pr-shepherd apply journal
+
+Append a list item to the ## Shepherd Journal section of a PR body.
+
+Usage:
+  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
+  pr-shepherd apply journal [PR] --file <path> [--dry-run] [--format text|json]
+  pr-shepherd apply journal [PR] --file - [--dry-run] [--format text|json]
+
+PR may be a number or GitHub pull request URL. An item must start with '- ' followed by text.
+Use --file to read an item from a file, or --file - to read it from stdin. Exactly one item source
+is required. --dry-run previews the resulting body without writing it.
+--help, -h                      Print this help and exit before GitHub I/O.`;
+    readonly "build-suggestion-patch": `pr-shepherd build-suggestion-patch
+
+Build a patch and commit instructions for one GitHub review thread containing a suggestion block.
+The command does not edit files or mutate git history.
+
+Usage:
+  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG
+                                      [--description DESC] [--format text|json]
+
+Flags:
+  --thread-id <id>       Review thread containing exactly one suggestion block. Required.
+  --message <text>       Suggested commit subject. Required and non-empty.
+  --description <text>   Optional longer commit body.
+  --format text|json     Output format. Default: text.
+
+The current branch must match the PR head ref and local HEAD must match the PR head SHA.
+--help, -h                      Print this help and exit before GitHub, git, config, or log I/O.`;
+    readonly admin: `pr-shepherd admin
+
+Administrative state and diagnostics commands.
+
+Usage:
+  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]
+  pr-shepherd admin log-file [--format text|json]
+
+Run 'pr-shepherd admin <clean|log-file> --help' for command-specific details.
+--help, -h                      Print this help and exit before any I/O.`;
+    readonly "admin clean": `pr-shepherd admin clean
+
+Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
+
+Usage:
+  pr-shepherd admin clean pr [number] [--dry-run] [--format text|json]
+  pr-shepherd admin clean branch [name] [--dry-run] [--format text|json]
+  pr-shepherd admin clean current [--dry-run] [--format text|json]
+  pr-shepherd admin clean repo [--dry-run] [--format text|json]
+  pr-shepherd admin clean all [--dry-run] [--format text|json]
+
+Variants remove state for one PR, branch, current branch, repository, or all repositories.
+Use --dry-run to preview paths without removing them.
+--help, -h                      Print this help and exit before any cleanup.`;
+    readonly "admin log-file": string;
+    readonly resolve: `pr-shepherd resolve
+
+Apply GitHub review-state mutations after fixes.
+
+Usage:
+  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]
+
+Flags:
+  --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
+                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
+                                  Note: comment IDs (PRRC_*) from gh api are not thread IDs and will fail.
+  --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>                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.
+                                  Must be a full 40-character lowercase hex SHA. Use $(git rev-parse HEAD).
+  --format text|json              Output format. Default: text.
+  --help, -h                      Print this help and exit before GitHub I/O.
+
+At least one non-empty action flag is required:
+  --reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids.
+
+PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
+Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
+    readonly "commit-suggestion": `pr-shepherd commit-suggestion
+
+Build a patch and commit instructions for one GitHub review thread containing a suggestion block.
+The command does not edit files or mutate git history.
+
+Usage:
+  pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG
+                                      [--description DESC] [--format text|json]
+
+Flags:
+  --thread-id <id>       Review thread ID containing exactly one suggestion to apply. Required.
+  --message <text>       Suggested commit subject. Required and must be non-empty.
+  --description <text>   Optional longer commit body.
+  --format text|json     Output format. Default: text.
+  --help, -h             Print this help and exit before GitHub, git, config, or log I/O.
+
+Preconditions:
+  The current branch must match the PR head ref, and local HEAD must match the PR head SHA.
+
+Exit codes:
+  0   suggestion patch and instructions produced
+  64  usage error (missing/invalid flag)
+  69  precondition unmet (thread ineligible, branch/SHA mismatch, no open PR)
+  See docs/exit-codes.md for the full sysexits.h table.`;
+    readonly "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; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
+    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate code action; run another iterate tick later.\n  MARK_READY  Draft PR was marked ready for review.\n  FIX_CODE    Apply fixes, commit, push, and run the printed apply command.\n  CANCEL      Terminal state: merged/closed or ready-delay elapsed.\n  ESCALATE    Terminal state requiring human direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes a single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly clean: `pr-shepherd clean
+
+Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
+
+Usage:
+  pr-shepherd clean pr [number] [--dry-run] [--format text|json]
+  pr-shepherd clean branch [name] [--dry-run] [--format text|json]
+  pr-shepherd clean current [--dry-run] [--format text|json]
+  pr-shepherd clean repo [--dry-run] [--format text|json]
+  pr-shepherd clean all [--dry-run] [--format text|json]
+
+Variants:
+  pr [number]          Remove state for one PR. Defaults to current branch PR.
+  branch [name]        Resolve a branch to its open PR, then remove that PR's state.
+                       Defaults to current branch.
+  current              Alias for branch against the current branch.
+  repo                 Remove all state for the current repository, including worktree logs.
+  all                  Remove all pr-shepherd state.
+
+Flags:
+  --dry-run            Preview paths without removing them.
+  --format text|json   Output format. Default: text.
+  --help, -h           Print this help and exit before any cleanup.
+
+Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
+    readonly journal: `pr-shepherd journal
+
+Append a list item to the ## Shepherd Journal section of a PR body.
+Creates the section at the end if absent. Idempotent — duplicate items are skipped.
+
+Usage:
+  pr-shepherd journal [PR] <item> [--dry-run] [--format text|json]
+  pr-shepherd journal [PR] --file <path> [--dry-run] [--format text|json]
+  pr-shepherd journal [PR] --file - [--dry-run] [--format text|json]
+
+  PR     PR number or GitHub pull request URL. Defaults to current branch PR.
+  item   Markdown list item: must start with "- " followed by non-whitespace text.
+         Example: '- Rejected suggestion: kept existing pattern for consistency.'
+         Provide it as a positional argument, or via --file to avoid shell-escaping
+         backticks and multi-line Markdown. Exactly one of the two is required.
+
+Flags:
+  --file <path>        Read the entry from a file instead of a positional argument.
+                        Pass --file - to read from stdin.
+  --dry-run            Preview the new PR body without writing it to GitHub.
+  --format text|json   Output format. Default: text.
+  --help, -h           Print this help and exit before any GitHub I/O.
+
+Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
+    readonly "log-file": "pr-shepherd log-file\n\nPrint the per-worktree append-only debug log path for the current repository.\nThe log is created by the first non-help pr-shepherd command that initializes logging.\n\nUsage:\n  pr-shepherd log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
+};