pr-shepherd 0.34.0 → 0.35.0

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

@@ -7,24 +7,23 @@ Usage:
   pr-shepherd --help | -h
   pr-shepherd [PR] [poll-flags] [iterate-flags]
   pr-shepherd iterate [PR] [iterate-flags]
-  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 journal [PR] <item> [--dry-run] [--format text|json]
-  pr-shepherd clean <pr|branch|current|repo|all> [value] [flags]
-  pr-shepherd log-file [--format text|json]
+  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 build-suggestion-patch [PR] --thread-id ID --message MSG [flags]
+  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]
+  pr-shepherd admin log-file [--format text|json]
 
 Commands:
   [PR]                 Poll until non-WAIT or timeout. This is the default command.
   iterate              Run one iterate tick (single-tick alias).
-  poll                 Re-run iterate while the action is WAIT, then print the final tick.
-  resolve              Apply review-state mutations (requires at least one action flag).
-  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.
-  journal              Append a list item to the ## Shepherd Journal section of a PR body.
-  clean                Remove pr-shepherd state files.
-  log-file             Print the per-worktree debug log path.
+  apply review         Apply review-state mutations after fixes.
+  apply files          Mark changed files as viewed in GitHub.
+  apply journal        Append a list item to the ## Shepherd Journal section of a PR body.
+  build-suggestion-patch
+                       Convert one GitHub suggestion thread into a patch and commit instructions.
+  admin clean          Remove pr-shepherd state files.
+  admin log-file       Print the per-worktree debug log path.
 
 PR argument:
   PR may be a number such as 42 or a GitHub pull request URL.
@@ -41,7 +40,7 @@ Iterate flags:
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
 
-Poll flags:
+Polling flags:
   --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.
   --timeout <duration>           Poll wall-clock cap. Bare number = seconds. Default: 4.5m.
   --quiet-status                 During WAIT polling, print only changed status snapshots.

package/bin/cli/help.d.mts

@@ -0,0 +1,236 @@
+export declare const 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.";
+    readonly top: "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.";
+};
+/** Resolve help keys for nested public commands before any command I/O. */
+export declare function helpKeyForArgs(args: string[]): keyof typeof USAGE;
+/** Prints usage for `key` to stdout and returns true if `--help` or `-h` is in args. */
+export declare function maybePrintHelp(args: string[], key: keyof typeof USAGE): boolean;

package/bin/cli/help.mjs

@@ -5,6 +5,23 @@ export const USAGE = {
     top: TOP_USAGE,
     ...COMMAND_USAGE,
 };
+/** Resolve help keys for nested public commands before any command I/O. */
+export function helpKeyForArgs(args) {
+    if (args[0] === "apply" && args[1] === "review")
+        return "apply review";
+    if (args[0] === "apply" && args[1] === "files")
+        return "apply files";
+    if (args[0] === "apply" && args[1] === "journal")
+        return "apply journal";
+    if (args[0] === "admin" && args[1] === "clean")
+        return "admin clean";
+    if (args[0] === "admin" && args[1] === "log-file")
+        return "admin log-file";
+    if (args[0] != null && args[0] in USAGE) {
+        return args[0];
+    }
+    return "top";
+}
 /** Prints usage for `key` to stdout and returns true if `--help` or `-h` is in args. */
 export function maybePrintHelp(args, key) {
     if (!hasFlag(args, "--help") && !hasFlag(args, "-h"))

package/bin/cli/iterate-emitter.d.mts

@@ -0,0 +1,8 @@
+import type { IterateResult } from "../types.mts";
+interface EmitIterateResultOpts {
+    format: "text" | "json";
+    verbose: boolean;
+    readyDelaySuffix?: string;
+}
+export declare function emitIterateResult(result: IterateResult, opts: EmitIterateResultOpts): void;
+export {};

package/bin/cli/iterate-flags.d.mts

@@ -0,0 +1,11 @@
+import type { loadConfig } from "../config/load.mts";
+interface IterateFlags {
+    readyDelaySuffix: string | undefined | null;
+    readyDelaySeconds: number;
+    stallTimeoutSuffix: string | undefined | null;
+    stallTimeoutSeconds: number;
+    noAutoMarkReady: boolean;
+    noAutoCancelActionable: boolean;
+}
+export declare function parseIterateFlags(extra: string[], cfg: ReturnType<typeof loadConfig>): IterateFlags;
+export {};

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

@@ -0,0 +1,19 @@
+import type { IterateResult } from "../types.mts";
+/**
+ * Format an IterateResult as human-readable Markdown.
+ *
+ * Load-bearing conventions the iterate skill relies on:
+ *   1. The H1 heading on line 1 contains `[<ACTION>]` — the action tag identifies
+ *      the output for logging and validation. Behavior is driven by `## Instructions`,
+ *      not by dispatching on the tag.
+ *   2. `[FIX_CODE]` wraps the `resolve` command under `## Post-fix push` in
+ *      backticks — the skill extracts the backticked content for execution.
+ *   3. Every action ends with a `## Instructions` section — numbered `1.`, `2.`, … —
+ *      that tells the agent exactly what to do with this output. The section is
+ *      unconditional: every action, every variant, always emits at least one step.
+ *      The skill simply follows those steps; it does not need its own dispatch table.
+ */
+export declare function formatIterateResult(result: IterateResult, opts?: {
+    verbose?: boolean;
+    readyDelaySuffix?: string;
+}): string;

package/bin/cli/iterate-instructions.d.mts

@@ -0,0 +1,6 @@
+import type { IterateResult } from "../types.mts";
+export declare function buildSimpleIterateInstructions(result: Exclude<IterateResult, {
+    action: "fix_code";
+}>): string[];
+export declare function adaptIterateLog(log: string): string;
+export declare function numberInstructions(instructions: string[]): string;

package/bin/cli/iterate-lean.d.mts

@@ -0,0 +1,12 @@
+import type { IterateResult } from "../types.mts";
+interface IterateProjectionOptions {
+    readyDelaySuffix?: string;
+}
+/**
+ * Project an IterateResult to a lean JSON shape for the default (non-verbose) output.
+ * Omits fields that are the trivial default (false, 0, empty) or state-gated fields
+ * outside the state where they are meaningful.
+ */
+export declare function projectIterateLean(result: IterateResult, opts?: IterateProjectionOptions): unknown;
+export declare function projectIterateVerbose(result: IterateResult, opts?: IterateProjectionOptions): unknown;
+export {};

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

@@ -0,0 +1,2 @@
+import type { JournalResult } from "../commands/journal/index.mts";
+export declare function formatJournalResult(result: JournalResult): string;

package/bin/cli/journal-formatter.mjs

@@ -0,0 +1,15 @@
+export function formatJournalResult(result) {
+    if (result.dryRun) {
+        const lines = ["Dry run — no body change written."];
+        if (result.previewBody !== undefined) {
+            lines.push("", result.previewBody);
+        }
+        return lines.join("\n");
+    }
+    if (!result.mutated)
+        return "No change — entry already present.";
+    if (!result.sectionExisted) {
+        return `Created ## Shepherd Journal section in PR #${result.prNumber}.`;
+    }
+    return `Appended to ## Shepherd Journal in PR #${result.prNumber}.`;
+}

package/bin/cli/journal-handler.d.mts

@@ -0,0 +1 @@
+export declare function handleJournal(args: string[], command?: "apply journal" | "journal"): Promise<void>;

package/bin/cli/journal-handler.mjs

@@ -3,7 +3,8 @@ import { EXIT, errorToExitCode } from "../exit-codes.mjs";
 import { runJournal } from "../commands/journal/index.mjs";
 import { getFlag, parsePrNumber } from "./args.mjs";
 import { USAGE } from "./help.mjs";
-export async function handleJournal(args) {
+import { formatJournalResult } from "./journal-formatter.mjs";
+export async function handleJournal(args, command = "apply journal") {
     for (const a of args) {
         if (!a.startsWith("--"))
             continue;
@@ -11,14 +12,14 @@ export async function handleJournal(args) {
             continue;
         if (a === "--file" || a.startsWith("--file="))
             continue;
-        process.stderr.write(`pr-shepherd: journal: unknown flag: "${a}"\n`);
+        process.stderr.write(`pr-shepherd: ${command}: unknown flag: "${a}"\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
     const { prNumber, extra } = parseJournalArgs(args);
     const filePath = getFlag(args, "--file");
     if (filePath !== null && extra[0]) {
-        process.stderr.write(`pr-shepherd: journal: provide the entry as a positional argument or via --file, not both\n`);
+        process.stderr.write(`pr-shepherd: ${command}: provide the entry as a positional argument or via --file, not both\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -27,12 +28,12 @@ export async function handleJournal(args) {
         rawItem = filePath !== null ? await readItemSource(filePath) : extra[0];
     }
     catch (e) {
-        process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
+        process.stderr.write(`pr-shepherd: ${command}: ${String(e)}\n`);
         process.exitCode = EXIT.NOINPUT;
         return;
     }
     if (rawItem === undefined) {
-        process.stderr.write(`${USAGE.journal}\n`);
+        process.stderr.write(`${USAGE[command]}\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -49,7 +50,7 @@ export async function handleJournal(args) {
         }
     }
     catch (e) {
-        process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
+        process.stderr.write(`pr-shepherd: ${command}: ${String(e)}\n`);
         process.exitCode = errorToExitCode(e);
     }
 }
@@ -96,17 +97,3 @@ function parseJournalArgs(args) {
     }
     return { prNumber, extra };
 }
-function formatJournalResult(result) {
-    if (result.dryRun) {
-        const lines = ["Dry run — no body change written."];
-        if (result.previewBody !== undefined) {
-            lines.push("", result.previewBody);
-        }
-        return lines.join("\n");
-    }
-    if (!result.mutated)
-        return "No change — entry already present.";
-    if (!result.sectionExisted)
-        return `Created ## Shepherd Journal section in PR #${result.prNumber}.`;
-    return `Appended to ## Shepherd Journal in PR #${result.prNumber}.`;
-}

package/bin/cli/list-formatters.d.mts

@@ -0,0 +1,76 @@
+import type { AuthorType, CommentAuthorAssociation, SuggestionBlock } from "../types.mts";
+import type { FirstLookThread, FirstLookComment } from "../types/report.mts";
+export declare function renderAuthor(author: string, authorType?: AuthorType, authorAssociation?: CommentAuthorAssociation): string;
+export declare function renderBodyPreview(body: string): string;
+export declare function renderThreadResolutionStatusTag(t: {
+    isOutdated?: boolean;
+    isMinimized?: boolean;
+}): string;
+interface ThreadBulletInput {
+    id: string;
+    reviewId?: string;
+    url?: string;
+    path?: string | null;
+    startLine?: number | null;
+    line?: number | null;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    comments?: Array<{
+        id: string;
+        author: string;
+        authorType?: AuthorType;
+        authorAssociation?: CommentAuthorAssociation;
+        body: string;
+        url: string;
+    }>;
+    suggestion?: SuggestionBlock;
+    edited?: boolean;
+}
+export declare function renderThreadBullet(t: ThreadBulletInput, opts?: {
+    statusTag?: string;
+    renderSuggestion?: boolean;
+    noBody?: boolean;
+    suppressEditedMarker?: boolean;
+}): string;
+export declare function renderThreadConversation(t: ThreadBulletInput): string;
+export declare function blockquote(body: string): string;
+export declare function renderCommentBullet(c: {
+    id: string;
+    url?: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+}, opts?: {
+    statusTag?: string;
+}): string;
+export declare function renderEditedCommentTag(c: {
+    edited?: boolean;
+}): string | undefined;
+export declare function renderReviewBullet(r: {
+    id: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body?: string;
+    staleBotCr?: boolean;
+    staleReview?: boolean;
+}, opts?: {
+    includeBody?: boolean;
+}): string;
+export declare function renderReviewListSection(heading: string, items: {
+    id: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body?: string;
+}[]): string | null;
+/**
+ * Build bullet strings for the `## First-look items` section.
+ * Threads that also appear in resolutionOnlyIds have their body suppressed
+ * (already shown in `## Review threads to resolve`).
+ */
+export declare function buildFirstLookBullets(firstLookThreads: FirstLookThread[], resolutionOnlyIds: Set<string>, firstLookComments: FirstLookComment[]): string[];
+export {};

package/bin/cli/list-formatters.mjs

@@ -1,8 +1,8 @@
 import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
 import { threadComments } from "../threads/transcript.mjs";
 const BODY_PREVIEW_MAX = 100;
-export function renderAuthor(author, authorType) {
-    return authorType ? `@${author} · ${authorType}` : `@${author}`;
+export function renderAuthor(author, authorType, authorAssociation) {
+    return [`@${author}`, authorType, authorAssociation].filter(Boolean).join(" · ");
 }
 export function renderBodyPreview(body) {
     const normalizedBody = body.replace(/\r\n?/g, "\n");
@@ -30,7 +30,7 @@ export function renderThreadBullet(t, opts = {}) {
     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)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType, t.authorAssociation)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
     if (!opts.noBody && (!t.comments || t.comments.length === 0)) {
         const legacyLine = `${bulletLine}: ${renderBodyPreview(t.body)}`;
         return t.suggestion && opts.renderSuggestion
@@ -53,9 +53,9 @@ export function renderThreadConversation(t) {
         .map((c) => {
         const heading = c.id
             ? c.url
-                ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType)})`
-                : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType)})`
-            : `#### (${renderAuthor(c.author, c.authorType)})`;
+                ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`
+                : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`
+            : `#### (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`;
         return `${heading}\n\n${blockquote(c.body)}`;
     })
         .join("\n\n");
@@ -73,7 +73,7 @@ function renderThreadCommentBullets(t) {
         const link = c.url ? ` [↗](${c.url})` : "";
         const id = c.id ? `\`commentId=${c.id}\`` : "comment";
         return [
-            `  - ${id}${link} (${renderAuthor(c.author, c.authorType)})`,
+            `  - ${id}${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`,
             indentBlockquote(c.body, "    "),
         ].join("\n");
     })
@@ -88,13 +88,13 @@ function indentBlockquote(body, indent) {
 export function renderCommentBullet(c, opts = {}) {
     const link = c.url ? ` [↗](${c.url})` : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
+    return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
 }
 export function renderEditedCommentTag(c) {
     return c.edited ? "[edited since first look]" : undefined;
 }
 export function renderReviewBullet(r, opts = {}) {
-    const base = `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})`;
+    const base = `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})`;
     const staleTag = r.staleReview
         ? " [stale — review is on an old commit, all threads resolved]"
         : "";

package/bin/cli/mark-files-as-viewed-flags.d.mts

@@ -0,0 +1,11 @@
+type ParseMarkFilesAsViewedResult = {
+    ok: true;
+    files: string[];
+    tests: boolean;
+    matchPatterns: string[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseMarkFilesAsViewedArgs(args: string[]): ParseMarkFilesAsViewedResult;
+export {};

package/bin/cli/mark-files-as-viewed-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { MarkFilesAsViewedResult } from "../commands/mark-files-as-viewed.mts";
+export declare function formatMarkFilesAsViewedResult(result: MarkFilesAsViewedResult): string;

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

@@ -0,0 +1,2 @@
+import type { ResolveResult } from "../comments/resolve.mts";
+export declare function formatMutateResult(result: ResolveResult): string;

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

@@ -0,0 +1 @@
+export declare function handlePoll(args: string[]): Promise<void>;