clud-bug 0.7.0-rc.2 → 0.7.0-rc.21

package/src/core/index.ts

@@ -116,7 +116,10 @@ export {
   WRITTEN_BY,
   SEVERITY_EMOJI as REVIEW_FILE_SEVERITY_EMOJI,
   type RenderReviewFileInput,
+  type RenderedFindingRef,
+  type CacheStats,
   type RenderMultiPassMarkdownInput,
+  type Consensus,
   type MultiPassReview,
   type UnifiedFinding,
   type PassAttribution,
@@ -124,6 +127,188 @@ export {
   type ReviewPassMode,
   type MultiPassVerdict,
 } from './review-writeback.js';
+// SPEC §7.2.1 formal-review event selector. Pure rule-table half of
+// clud-bug-app's `lib/formal-review.ts`; the Octokit-side IO wrapper
+// (`postFormalReview`) stays App-side. v0.7.0-rc.3 adds the
+// `authorAssociation` extension so a clean review on an external
+// contributor's PR routes to COMMENT (not APPROVE) — the canonical
+// ruleset's `required_approving_review_count: 1` floor then requires
+// a human reviewer.
+export {
+  selectReviewEvent,
+  type FormalReviewEvent,
+  type AuthorAssociation,
+  type SelectReviewEventInput,
+} from './formal-review.js';
+// SPEC §1.8.1 Resolved / Still-open block helpers. `parsePriorReviewFile`
+// reads a prior `docs/reviews/PR-<n>.md`; `diffFindings` splits prior vs
+// current into resolved + still-open lists that `renderReviewFile`
+// emits as the §1.8.1 blocks. Identity scheme is shareable with future
+// inline-thread anchoring in clud-bug-app.
+export {
+  parsePriorReviewFile,
+  diffFindings,
+  findingIdentity,
+  type ParsedFinding,
+  type ParsedReview,
+} from './diff-findings.js';
+// Wave 5a — D.2.X per-finding inline review threads. Pure helpers
+// (anchor detection, comment rendering, plan partitioning) + the GraphQL
+// constants the CLI's `post-inline-threads` verb invokes via `gh api`.
+// `findingId` returns the SHA-256[:16] hash and is distinct from the
+// plain-string `findingIdentity` above (both serve different matchers).
+//
+// Wave 5b additions: `parseThreadBody` (inverts renderThreadBody) +
+// `ADD_REPLY_MUTATION` (for posting the auto-resolve marker reply
+// before resolving a thread).
+export {
+  findingId,
+  parseHeadLines,
+  findingAnchorable,
+  extractAnchorContext,
+  renderThreadBody,
+  extractFindingIdFromBody,
+  parseThreadBody,
+  planInlineThreads,
+  REVIEW_THREADS_QUERY,
+  REVIEW_THREADS_STATE_QUERY,
+  RESOLVE_THREAD_MUTATION,
+  ADD_REPLY_MUTATION,
+  type Severity as InlineThreadSeverity,
+  type FindingForThread,
+  type DiffFile,
+  type InlineCommentPlan,
+  type PlanInlineThreadsResult,
+} from './inline-threads.js';
+// Wave 5b — D.2.6 auto-resolve on fix-push. Pure rule tables + config
+// merge + marker rendering. The CLI's `resolve-threads` verb owns the
+// Anthropic Messages call + GraphQL mutations; `runAutoResolve` is
+// pure modulo the injected verifier callback.
+export {
+  resolveAutoResolveConfig,
+  readAutoResolveConfigFromCludBug,
+  runAutoResolve,
+  applyResolutionRules,
+  renderAutoResolveMarker,
+  DEFAULT_AUTO_RESOLVE_CONFIG,
+  type AutoResolveConfig,
+  type PriorThread,
+  type PriorFinding,
+  type ThreadAction,
+  type AutoResolveInput,
+  type AutoResolveResult,
+  type VerifyOutcome,
+} from './auto-resolve.js';
+export {
+  VERIFIER_SYSTEM,
+  buildVerifierSystem,
+  buildVerifierPrompt,
+  parseVerifierResponse,
+  type VerifierOutputMode,
+  type VerifySingleFindingInput,
+} from './resolve-verifier.js';
+// SPEC §7 canonical-ruleset applier. Pure diff + idempotent-PATCH logic;
+// CLI side wraps `gh api` in an Octokit-like adapter and the App passes
+// its real Octokit instance. Shipped in v0.7.0-rc.4 for Marketplace prep
+// (Phase 6 task #227).
+export {
+  applyCanonicalRuleset,
+  loadCanonicalV1,
+  type CanonicalRuleset,
+  type OctokitLike,
+  type ApplyCanonicalRulesetParams,
+  type ApplyResult,
+} from './configure-github.js';
+// Wave 6b — review-planning "brain" ported from clud-bug-app/lib. Three pure
+// modules: the multi-pass config resolver (`review-plan`), the Layer-1 cost
+// gate (`budget-plan`), and the multi-pass aggregator (`multi-pass-aggregate`).
+//
+// `ReviewPassMode` is intentionally NOT re-exported here — `review-writeback`
+// above already owns that name in the barrel (both declarations are the same
+// `'cross-check' | 'consensus' | 'independent'` union). Likewise the
+// aggregator's result types (`MultiPassReview`, `UnifiedFinding`,
+// `PassAttribution`, `PassSource`) come from `review-writeback` and are NOT
+// re-declared by the aggregator module — it imports them.
+export {
+  readReviewPassesConfig,
+  extractSkillReviewPassesOverride,
+  resolveReviewPasses,
+  roleForPass,
+  anyMultiPass,
+  totalPassCount,
+  REVIEW_PASS_MODES,
+  MAX_PASSES,
+  MIN_PASSES,
+  BUILTIN_DEFAULT,
+  BUILTIN_ROLES,
+  type ApplyTo,
+  type ReviewPassesEntry,
+  type ReviewRoleTier,
+  type ReviewRole,
+  type ResolvedReviewPasses,
+  type ReviewPassesConfig,
+  type SkillReviewPassesFrontmatter,
+  type ReviewPlanSkill,
+  type ResolveReviewPassesInput,
+  type ResolveReviewPassesResult,
+} from './review-plan.js';
+export {
+  perCallCeiling,
+  estimateBudget,
+  estimateVerifierBudget,
+  __setModelCeilingForTests,
+  DEFAULT_PER_PR_CAP_USD,
+  DEFAULT_VERIFIER_PER_PR_CAP_USD,
+  type BudgetEstimateInput,
+  type BudgetEstimate,
+  type BudgetVerdict,
+  type VerifierBudgetInput,
+  type VerifierBudgetEstimate,
+  type VerifierBudgetVerdict,
+} from './budget-plan.js';
+export {
+  planReview,
+  LARGE_DIFF_THRESHOLD_BYTES,
+  type PlanReviewInput,
+  type ReviewPlan,
+  type ReviewTrigger,
+  type TierDownReason,
+} from './plan-review.js';
+export {
+  aggregatePasses,
+  deriveConsensus,
+  resolveVerdict,
+  shouldEscalate,
+  type CrossCheckVerdict,
+  type CrossCheckPassResult,
+  type AggregateInput,
+  type EscalationInput,
+} from './multi-pass-aggregate.js';
+export {
+  readDesignConfig,
+  shouldRunDesign,
+  BUILTIN_DESIGN_CONFIG,
+  type DesignConfig,
+  type DesignGate,
+} from './design.js';
+export {
+  readReviewContext,
+  extractPrContext,
+  fenceUntrustedContext,
+  EMPTY_REVIEW_CONTEXT,
+  MAX_REVIEW_CONTEXT_BYTES,
+  type ReviewContextConfig,
+} from './review-context.js';
+export {
+  deriveCheck,
+  normalizeVerdict,
+  CLUD_BUG_CHECK_NAME,
+  type ReviewVerdict,
+  type CheckConclusion,
+  type CheckSource,
+  type DerivedCheck,
+  type DeriveCheckInput,
+} from './check-verdict.js';
 export {
   API_BASE,
   MAX_SKILLS,
@@ -133,6 +318,7 @@ export {
   readReviewMode,
   readAppliesTo,
   appliesToPr,
+  appliesToAuthor,
   partitionByReviewMode,
   extractPerSkillLine,
   selectReviewHeader,
@@ -152,4 +338,6 @@ export {
   type SkillFrontmatter,
   type SkillSource,
   type SkillReviewMode,
+  type SkillKind,
+  type VoiceScope,
 } from './skills.js';

package/src/core/inline-threads.ts

@@ -0,0 +1,471 @@
+// Wave 5a — D.2.X inline review threads (npm workflow parity, OSS port).
+//
+// This module holds the pure helpers + GraphQL operation strings that BOTH
+// the npm workflow path and the hosted clud-bug-app use to attach a
+// per-finding inline review thread to the PR (replacing the legacy
+// "one big summary comment listing every finding" UX).
+//
+// The split between npm and app:
+//   - npm path (this package's CLI verb `post-inline-threads`) is stateless:
+//     it shells out to `gh api` for the REST createReview + `gh api graphql`
+//     for the GraphQL thread-id lookup, then EXITS. No persistent record —
+//     Wave 5b's auto-resolve re-queries GitHub on the next push and re-derives
+//     finding IDs from the comment-body markers we embed here.
+//   - app path keeps its Redis-backed persistence for performance (cross-
+//     push thread correlation without re-querying GraphQL every time). The
+//     pure helpers below are designed so a future Wave 5c swap can have the
+//     App import from this module + drop its local duplicates.
+//
+// Designed to share `findingId` semantics with clud-bug-app's
+// `lib/inline-threads.ts:findingId` (SHA-256 of the canonical 5-tuple,
+// truncated to 16 hex chars) so threads posted by one consumer stay
+// matchable by the other after the App migrates.
+
+import { createHash } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type Severity = 'critical' | 'minor' | 'preexisting';
+
+/**
+ * Minimal shape this module needs from a review finding. Both the npm CLI
+ * and the App's `Finding` type satisfy this; the App also carries
+ * `reasoning` + nullable `file`/`line` which we tolerate via the optional
+ * fields below.
+ */
+export interface FindingForThread {
+  severity: Severity;
+  skill: string;
+  file?: string;
+  line?: number;
+  summary: string;
+  reasoning?: string;
+}
+
+/**
+ * Per-file unified-diff entry. Matches the shape returned by `gh api
+ * repos/{owner}/{repo}/pulls/{n}/files` (after JSON.parse) AND
+ * `octokit.rest.pulls.listFiles(...).data` so the App can pass either
+ * directly.
+ */
+export interface DiffFile {
+  filename: string;
+  patch?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Stable finding id — SHA-256 of the canonical 5-tuple, truncated to 16 hex.
+// ---------------------------------------------------------------------------
+
+/**
+ * Hashes the canonical `${file}:${line}:${severity}:${skill}:${summary[:100]}`
+ * tuple to 16 hex characters. Stable across consumers — the App computes
+ * the same hash for the same finding, so threads posted by one consumer
+ * stay matchable by the other.
+ *
+ * Summary is truncated to 100 chars BEFORE hashing so small wording tweaks
+ * on subsequent review passes don't generate a fresh id and orphan the
+ * prior thread.
+ *
+ * Distinct from `findingIdentity` in `./diff-findings` (which returns the
+ * plain unhashed string — used by the Resolved/Still-open block matcher).
+ * Both helpers coexist on purpose: the unhashed string is human-readable
+ * for in-prose matching; the hash is short + collision-safe for embedding
+ * in `<!-- finding-id: ... -->` comment-body markers.
+ */
+export function findingId(finding: {
+  file?: string;
+  line?: number;
+  severity: Severity;
+  skill: string;
+  summary: string;
+}): string {
+  const file = finding.file ?? '<no-file>';
+  const line = finding.line ?? 0;
+  const summary = finding.summary.slice(0, 100);
+  const payload = `${file}:${line}:${finding.severity}:${finding.skill}:${summary}`;
+  return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+
+// ---------------------------------------------------------------------------
+// Diff anchor detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the set of 1-indexed HEAD-side line numbers a unified-diff patch
+ * touches (added + context lines). GitHub only accepts inline review
+ * comments on lines that appear in the diff, so this gates whether a
+ * finding's `line` can become a thread.
+ *
+ * "Touched" = appears on the RIGHT side of the unified diff: added (`+`)
+ * lines OR unchanged context (` `) lines inside any hunk. Removed (`-`)
+ * lines are LEFT-side only and can't anchor inline comments.
+ *
+ * If `patch` is undefined (binary file, GitHub truncation) returns an empty
+ * set — the caller falls back to the summary comment for those findings.
+ */
+export function parseHeadLines(patch: string | undefined): Set<number> {
+  const lines = new Set<number>();
+  if (!patch) return lines;
+
+  // Hunk header: @@ -oldStart,oldLines +newStart,newLines @@
+  // newLines defaults to 1 when omitted.
+  const hunkHeaderRe = /^@@\s+-\d+(?:,\d+)?\s+\+(\d+)(?:,(\d+))?\s+@@/;
+
+  let newLine = 0;
+  let inHunk = false;
+  for (const rawLine of patch.split('\n')) {
+    const m = rawLine.match(hunkHeaderRe);
+    if (m) {
+      newLine = Number.parseInt(m[1]!, 10);
+      inHunk = true;
+      continue;
+    }
+    if (!inHunk) continue;
+
+    if (rawLine.startsWith('+') && !rawLine.startsWith('+++')) {
+      lines.add(newLine);
+      newLine++;
+    } else if (rawLine.startsWith('-') && !rawLine.startsWith('---')) {
+      // LEFT-side only — does not advance the newLine counter.
+    } else if (rawLine.startsWith('\\')) {
+      // "" — doesn't advance.
+    } else {
+      // Context line — counts as a HEAD-side line.
+      lines.add(newLine);
+      newLine++;
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Returns true when the finding's `(file, line)` can be anchored as an
+ * inline comment on the current diff. `diffFiles` is the per-file diff
+ * (as returned by `gh api repos/.../pulls/.../files`).
+ */
+export function findingAnchorable(
+  finding: { file?: string; line?: number },
+  diffFiles: ReadonlyArray<DiffFile>,
+): boolean {
+  if (!finding.file || !finding.line) return false;
+  const file = diffFiles.find((f) => f.filename === finding.file);
+  if (!file) return false;
+  return parseHeadLines(file.patch).has(finding.line);
+}
+
+// ---------------------------------------------------------------------------
+// Context extraction for the verifier (consumed in Wave 5b)
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the `{codeBefore, codeAfter, diffAtAnchor?}` triple Wave 5b's
+ * auto-resolve verifier consumes for a single finding, pulled out of the
+ * unified-diff hunk that touches the finding's line.
+ *
+ * Works entirely from the in-hand patch — no fresh API calls. The patch
+ * already encodes BEFORE (lines with `-` or context) and AFTER (lines with
+ * `+` or context) for every hunk the PR touches.
+ *
+ * Returns empty strings for `codeBefore`/`codeAfter` when the finding's
+ * file isn't in the diff at all. The verifier sees "unchanged" and
+ * typically returns NOT_ADDRESSED / UNCERTAIN, which is the correct
+ * behavior — an unchanged file isn't a fix.
+ */
+export function extractAnchorContext(
+  finding: { file?: string; line?: number },
+  diffFiles: ReadonlyArray<DiffFile>,
+): { codeBefore: string; codeAfter: string; diffAtAnchor?: string } {
+  if (!finding.file || !finding.line) {
+    return { codeBefore: '', codeAfter: '' };
+  }
+  const file = diffFiles.find((f) => f.filename === finding.file);
+  if (!file || !file.patch) {
+    return { codeBefore: '', codeAfter: '' };
+  }
+
+  // Locate the hunk whose new-side range contains finding.line.
+  const hunkHeaderRe = /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/;
+  const patchLines = file.patch.split('\n');
+  let currentHunkStart = -1;
+
+  for (let i = 0; i < patchLines.length; i++) {
+    const m = patchLines[i]!.match(hunkHeaderRe);
+    if (!m) continue;
+    const newStart = Number.parseInt(m[3]!, 10);
+    const newLen = m[4] !== undefined ? Number.parseInt(m[4]!, 10) : 1;
+    if (
+      finding.line >= newStart &&
+      finding.line < newStart + Math.max(newLen, 1)
+    ) {
+      currentHunkStart = i;
+      break;
+    }
+  }
+
+  if (currentHunkStart < 0) {
+    return { codeBefore: '', codeAfter: '' };
+  }
+
+  const before: string[] = [];
+  const after: string[] = [];
+  const hunkBody: string[] = [patchLines[currentHunkStart]!];
+
+  for (let i = currentHunkStart + 1; i < patchLines.length; i++) {
+    const line = patchLines[i]!;
+    if (line.match(hunkHeaderRe)) break;
+    hunkBody.push(line);
+
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      after.push(line.slice(1));
+    } else if (line.startsWith('-') && !line.startsWith('---')) {
+      before.push(line.slice(1));
+    } else if (line.startsWith('\\')) {
+      // No-newline marker — skip.
+    } else if (line.length > 0) {
+      // Context line — appears on both sides.
+      const stripped = line.startsWith(' ') ? line.slice(1) : line;
+      before.push(stripped);
+      after.push(stripped);
+    }
+  }
+
+  return {
+    codeBefore: before.join('\n'),
+    codeAfter: after.join('\n'),
+    diffAtAnchor: hunkBody.join('\n'),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Comment body rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Body for a single inline-thread comment. Includes a hidden HTML marker
+ * carrying `findingId` so Wave 5b's auto-resolve can recover the canonical
+ * id from the thread's first comment body without persisting state.
+ */
+export function renderThreadBody(finding: FindingForThread): string {
+  const id = findingId(finding);
+  const severityBadge = finding.severity === 'critical' ? '🔴' : '🟡';
+  const header = `${severityBadge} \`${finding.skill}\``;
+  const body = finding.summary.trim();
+  const reasoning = finding.reasoning ? `\n\n${finding.reasoning.trim()}` : '';
+  return `<!-- finding-id: ${id} -->\n${header}\n\n${body}${reasoning}`;
+}
+
+/**
+ * Extracts the hashed `findingId` from a thread comment body that was
+ * rendered by `renderThreadBody`. Returns null when the marker is absent
+ * (a manual reply, or a comment posted by a different tool).
+ *
+ * Used by Wave 5b's auto-resolve to re-derive finding ids from existing
+ * GitHub threads on a stateless re-run.
+ */
+export function extractFindingIdFromBody(body: string): string | null {
+  // Anchor to start-of-string so a user reply that quotes the marker can't be
+  // misattributed as bot-authored. `renderThreadBody` always places the marker
+  // on line 1 — anything else is suspect input.
+  const m = body.match(/^<!--\s*finding-id:\s*([a-f0-9]{16})\s*-->/);
+  return m ? m[1]! : null;
+}
+
+/**
+ * Wave 5b — invert `renderThreadBody` to recover the original finding
+ * tuple from a bot-authored thread comment. The fix-push auto-resolve
+ * CLI verb uses this to reconstruct `PriorFinding` from the GraphQL
+ * `reviewThreads` response without persistent state.
+ *
+ * Returns null when the body doesn't match the canonical shape
+ * `<!-- finding-id: XX -->\n🔴|🟡 \`skill\`\n\nsummary[\n\nreasoning]`.
+ * Same start-anchored posture as `extractFindingIdFromBody` for anti-
+ * injection: a user reply that quotes the marker mid-body won't be
+ * misattributed as bot-authored.
+ */
+export function parseThreadBody(body: string): {
+  findingId: string;
+  severity: Severity;
+  skill: string;
+  summary: string;
+  reasoning?: string;
+} | null {
+  // Marker (line 1), header (line 2: badge + backticked skill), blank,
+  // summary, optional blank + reasoning. The header line shape:
+  //   `🔴 \`critical-issues-only\``  or  `🟡 \`magic-numbers\``
+  const re =
+    /^<!--\s*finding-id:\s*([a-f0-9]{16})\s*-->\n(🔴|🟡)\s+`([^`]+)`\n\n([\s\S]+?)(?:\n\n([\s\S]+))?$/;
+  const m = body.match(re);
+  if (!m) return null;
+  const [, findingId, badge, skill, summary, reasoning] = m;
+  const severity: Severity = badge === '🔴' ? 'critical' : 'minor';
+  const out: {
+    findingId: string;
+    severity: Severity;
+    skill: string;
+    summary: string;
+    reasoning?: string;
+  } = {
+    findingId: findingId!,
+    severity,
+    skill: skill!,
+    summary: summary!.trim(),
+  };
+  if (reasoning && reasoning.trim()) out.reasoning = reasoning.trim();
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Inline-thread posting plan
+// ---------------------------------------------------------------------------
+
+/**
+ * One entry in the createReview `comments[]` array. Matches GitHub's REST
+ * shape exactly so callers can JSON.stringify directly into a `gh api` body.
+ */
+export interface InlineCommentPlan {
+  path: string;
+  line: number;
+  side: 'RIGHT';
+  body: string;
+}
+
+export interface PlanInlineThreadsResult {
+  /** Comment entries for the createReview `comments[]` field. */
+  comments: InlineCommentPlan[];
+  /** Findings the diff couldn't anchor (file or line not in any hunk). */
+  skipped: FindingForThread[];
+  /** Findings filtered out because severity is 'preexisting' (informational only). */
+  preexisting: FindingForThread[];
+}
+
+/**
+ * Partitions a flat findings list into the `comments[]` body for
+ * `POST /repos/:owner/:repo/pulls/:n/reviews` + the findings the caller
+ * should surface elsewhere (summary comment for `skipped`; never for
+ * `preexisting`).
+ *
+ * Pure function — no I/O. The CLI verb uses this to compute the API body;
+ * the App can use it after Wave 5c migration to share the same partitioning.
+ */
+export function planInlineThreads(
+  findings: ReadonlyArray<FindingForThread>,
+  diffFiles: ReadonlyArray<DiffFile>,
+): PlanInlineThreadsResult {
+  const comments: InlineCommentPlan[] = [];
+  const skipped: FindingForThread[] = [];
+  const preexisting: FindingForThread[] = [];
+
+  for (const f of findings) {
+    if (f.severity === 'preexisting') {
+      preexisting.push(f);
+      continue;
+    }
+    if (!findingAnchorable(f, diffFiles)) {
+      skipped.push(f);
+      continue;
+    }
+    comments.push({
+      path: f.file!,
+      line: f.line!,
+      side: 'RIGHT',
+      body: renderThreadBody(f),
+    });
+  }
+
+  return { comments, skipped, preexisting };
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL operations — pinned to module scope so callers (and tests) can
+// reference the same query strings as the App.
+// ---------------------------------------------------------------------------
+
+// Wave 5b update — `author { login }` added so the resolve-threads CLI
+// verb can filter to bot-authored threads. Without this, the bot-filter
+// reads `comments[0].author?.login` as undefined and accepts everything,
+// which would feed user-authored threads (that happen to start with the
+// marker) into the verifier. Additive change — Wave 5a consumers
+// (post-inline-threads) didn't read `author` so they're unaffected.
+export const REVIEW_THREADS_QUERY = `
+  query ReviewThreads($owner: String!, $repo: String!, $pr: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $pr) {
+        reviewThreads(first: 100) {
+          nodes {
+            id
+            isResolved
+            comments(first: 100) {
+              nodes {
+                databaseId
+                path
+                line
+                originalLine
+                body
+                author {
+                  login
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+// Includes `body` (unlike the App's lighter state query, which omits it) so
+// Wave 5b's auto-resolve can re-derive the `findingId` from the
+// `<!-- finding-id: ... -->` marker on each thread's first comment WITHOUT
+// persisting state between fix-pushes. The npm workflow is stateless; the
+// body field is the substitute for Redis-backed thread-id correlation.
+export const REVIEW_THREADS_STATE_QUERY = `
+  query ReviewThreadStates($owner: String!, $repo: String!, $pr: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $pr) {
+        reviewThreads(first: 100) {
+          nodes {
+            id
+            isResolved
+            comments(first: 1) {
+              nodes {
+                databaseId
+                body
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+export const RESOLVE_THREAD_MUTATION = `
+  mutation ResolveThread($threadId: ID!) {
+    resolveReviewThread(input: { threadId: $threadId }) {
+      thread {
+        isResolved
+      }
+    }
+  }
+`;
+
+// Wave 5b — post a reply on a review thread (used to attach the
+// auto-resolve marker explaining the verifier's verdict) BEFORE
+// calling `RESOLVE_THREAD_MUTATION`. The reply is visible in the PR
+// timeline so reviewers can audit why the bot auto-resolved.
+export const ADD_REPLY_MUTATION = `
+  mutation AddThreadReply($threadId: ID!, $body: String!) {
+    addPullRequestReviewThreadReply(
+      input: { pullRequestReviewThreadId: $threadId, body: $body }
+    ) {
+      comment {
+        id
+        body
+      }
+    }
+  }
+`;