pr-shepherd 0.34.0 → 0.35.0

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/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/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 while the action is WAIT. Print only the final tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, FIX_CODE, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. With --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. Bare number = seconds. Default: 4.5m.\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, 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.\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.";
+};

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

@@ -1,6 +1,111 @@
+/* eslint-disable max-lines */
 import { LOG_FILE_USAGE } from "./help-log-file-page.mjs";
-import { ITERATE_USAGE, POLL_USAGE } from "./help-iterate-poll-pages.mjs";
+import { DEFAULT_USAGE, ITERATE_USAGE, POLL_USAGE } from "./help-iterate-poll-pages.mjs";
 export const COMMAND_USAGE = {
+    default: DEFAULT_USAGE,
+    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.`,
+    "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.`,
+    "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.`,
+    "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.`,
+    "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.`,
+    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.`,
+    "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.`,
+    "admin log-file": LOG_FILE_USAGE.replaceAll("pr-shepherd log-file", "pr-shepherd admin log-file"),
     resolve: `pr-shepherd resolve
 
 Apply GitHub review-state mutations after fixes.

package/bin/cli/help-iterate-poll-pages.d.mts

@@ -0,0 +1,4 @@
+export declare const ITERATE_USAGE = "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).";
+export declare const POLL_USAGE = "pr-shepherd poll\n\nRun iterate repeatedly while the action is WAIT. Print only the final tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, FIX_CODE, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. With --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. Bare number = seconds. Default: 4.5m.\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, 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.\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).";
+/** Public help page for the default PR polling invocation. */
+export declare const DEFAULT_USAGE: string;

package/bin/cli/help-iterate-poll-pages.mjs

@@ -18,9 +18,9 @@ Iterate flags:
 Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).
 
 Actions:
-  WAIT        No immediate code action; recheck later or use pr-shepherd poll.
+  WAIT        No immediate code action; run another iterate tick later.
   MARK_READY  Draft PR was marked ready for review.
-  FIX_CODE    Apply fixes, commit, push, and run the printed resolve command.
+  FIX_CODE    Apply fixes, commit, push, and run the printed apply command.
   CANCEL      Terminal state: merged/closed or ready-delay elapsed.
   ESCALATE    Terminal state requiring human direction.
 
@@ -70,3 +70,5 @@ Exit codes: same as iterate (the final tick's action/reason decides the code).
   13  ESCALATE
   14  CANCEL (closed without merging)
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
+/** Public help page for the default PR polling invocation. */
+export const DEFAULT_USAGE = POLL_USAGE.replaceAll("pr-shepherd poll", "pr-shepherd [PR]");

package/bin/cli/help-log-file-page.d.mts

@@ -0,0 +1 @@
+export declare const LOG_FILE_USAGE = "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.";

package/bin/cli/help-top-page.d.mts

@@ -0,0 +1 @@
+export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark changed files as viewed in GitHub.\n  apply journal        Append a list item to the ## Shepherd Journal section of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\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\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap. Bare number = seconds. Default: 4.5m.\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\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\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)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";