@testzugang/pi-pr-findings 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# @testzugang/pi-pr-findings
+
+Fetch and group GitHub PR review findings by severity in Pi.
+
+## Install
+
+```bash
+pi install npm:@testzugang/pi-pr-findings
+```
+
+## Usage
+
+```text
+/skill:pr-findings
+```

package/extensions/pr-findings/index.ts

@@ -0,0 +1,969 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+type ExecResult = {
+  code: number | null;
+  stdout?: string;
+  stderr?: string;
+};
+
+type Severity = "blocker" | "warning" | "nit" | "all";
+type WaitMode = "new-review-activity" | "checks-finished";
+
+type FindingsOptions = {
+  prNumber?: number;
+  repo?: string;
+  unresolved: boolean;
+  severity: Severity;
+  includeStale: boolean;
+  mine: boolean;
+  waitForNextReview: boolean;
+  waitMode: WaitMode;
+  waitTimeoutSec: number;
+  waitPollSec: number;
+};
+
+type ActivitySnapshot = {
+  summaryCount: number;
+  inlineCount: number;
+  latestAtMs: number;
+};
+
+type PrSummaryComment = {
+  id: string;
+  author: string;
+  createdAt: string;
+  body: string;
+  url: string;
+};
+
+type InlineComment = {
+  id: string;
+  author: string;
+  createdAt: string;
+  path: string;
+  line: number | null;
+  body: string;
+  commitId: string;
+  url: string;
+  isOutdated: boolean;
+  isResolved: boolean;
+};
+
+type FindingsData = {
+  pr: {
+    number: number;
+    state: string;
+    headSha: string;
+    url: string;
+  };
+  viewerLogin: string;
+  checks: Array<{
+    name: string;
+    conclusion: string;
+    url: string;
+  }>;
+  summaryComments: PrSummaryComment[];
+  inlineComments: InlineComment[];
+};
+
+const EXEC_TIMEOUT_MS = 20_000;
+
+const DROP_AUTHORS = new Set([
+  "sonarqubecloud[bot]",
+  "sonarcloud[bot]",
+  "dependabot[bot]",
+  "github-actions[bot]",
+]);
+
+const SECTION_HEADER_RE =
+  /^#{1,6}\s*(?:🔴|🟡|🔵|✅)?\s*(blockers?|warnings?|nits?|approvals?|strengths?|suggestions?).*$/gim;
+const NUMBERED_ITEM_RE = /^\s*\d+\.\s+/gm;
+
+const DEFAULTS = {
+  severity: "all" as Severity,
+  unresolved: false,
+  includeStale: false,
+  mine: false,
+  waitForNextReview: false,
+  waitMode: "new-review-activity" as WaitMode,
+  waitTimeoutSec: 60,
+  waitPollSec: 30,
+};
+
+export default function registerPrFindings(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "pr_findings",
+    label: "PR Findings",
+    description:
+      "Fetch GitHub PR review findings via gh, grouped by severity, with optional wait for fresh review activity.",
+    promptSnippet: "Fetch GitHub PR findings and summarize by severity",
+    promptGuidelines: [
+      "Use waitForNextReview=true after pushing fixes so you don't read stale findings before the next review run finishes.",
+      "Default wait timeout is 60s with 30s polling when waiting is enabled.",
+    ],
+    parameters: Type.Object({
+      prNumber: Type.Optional(Type.Number({ description: "PR number" })),
+      repo: Type.Optional(
+        Type.String({ description: "Repository in owner/repo format" }),
+      ),
+      unresolved: Type.Optional(
+        Type.Boolean({ description: "Show unresolved findings only" }),
+      ),
+      severity: Type.Optional(
+        Type.Union([
+          Type.Literal("blocker"),
+          Type.Literal("warning"),
+          Type.Literal("nit"),
+          Type.Literal("all"),
+        ]),
+      ),
+      includeStale: Type.Optional(
+        Type.Boolean({ description: "Include stale findings on old commits" }),
+      ),
+      mine: Type.Optional(
+        Type.Boolean({
+          description: "Show only findings authored by current gh user",
+        }),
+      ),
+      waitForNextReview: Type.Optional(
+        Type.Boolean({
+          description:
+            "Wait for new review activity before reading findings (useful right after a push)",
+        }),
+      ),
+      waitMode: Type.Optional(
+        Type.Union([
+          Type.Literal("new-review-activity"),
+          Type.Literal("checks-finished"),
+        ]),
+      ),
+      waitTimeoutSec: Type.Optional(
+        Type.Number({
+          description: "Timeout for waiting mode in seconds (default 60)",
+        }),
+      ),
+      waitPollSec: Type.Optional(
+        Type.Number({
+          description:
+            "Polling interval for waiting mode in seconds (default 30)",
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      await ensureGhAvailable(pi);
+
+      const options = normalizeOptions(params);
+      const repo = await resolveRepo(pi, options.repo);
+      const prNumber = await resolvePrNumber(pi, repo, options.prNumber);
+
+      let waitSummary = "";
+      if (options.waitForNextReview) {
+        if (options.waitMode === "checks-finished") {
+          const waited = await waitForChecksFinished(
+            pi,
+            repo,
+            prNumber,
+            options,
+          );
+          waitSummary = waited
+            ? "Waited for checks to finish before collecting findings."
+            : "Wait timeout reached before checks finished; collected current findings.";
+        } else {
+          const waited = await waitForNewReviewActivity(
+            pi,
+            repo,
+            prNumber,
+            options,
+          );
+          waitSummary = waited
+            ? "Detected new review activity before collecting findings."
+            : "Wait timeout reached before new review activity; collected current findings.";
+        }
+      }
+
+      const data = await fetchFindingsData(pi, repo, prNumber);
+      const report = renderMarkdown(data, options);
+      const closing = closingLine(report);
+      const text = waitSummary
+        ? `${report}\n${closing}\n\n${waitSummary}`
+        : `${report}\n${closing}`;
+
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          repo,
+          prNumber,
+          waitForNextReview: options.waitForNextReview,
+          waitMode: options.waitMode,
+          waitTimeoutSec: options.waitTimeoutSec,
+          waitPollSec: options.waitPollSec,
+        },
+      };
+    },
+  });
+}
+
+function normalizeOptions(params: Record<string, unknown>): FindingsOptions {
+  const severity = normalizeSeverity(params.severity);
+  const waitMode = normalizeWaitMode(params.waitMode);
+  const waitTimeoutSec = clampPositiveNumber(
+    params.waitTimeoutSec,
+    DEFAULTS.waitTimeoutSec,
+    5,
+    3600,
+  );
+  const waitPollSec = clampPositiveNumber(
+    params.waitPollSec,
+    DEFAULTS.waitPollSec,
+    5,
+    600,
+  );
+
+  return {
+    prNumber:
+      typeof params.prNumber === "number" && Number.isInteger(params.prNumber)
+        ? params.prNumber
+        : undefined,
+    repo: normalizeRepo(params.repo),
+    unresolved: params.unresolved === true,
+    severity,
+    includeStale: params.includeStale === true,
+    mine: params.mine === true,
+    waitForNextReview: params.waitForNextReview === true,
+    waitMode,
+    waitTimeoutSec,
+    waitPollSec,
+  };
+}
+
+function normalizeSeverity(value: unknown): Severity {
+  if (value === "blocker" || value === "warning" || value === "nit") {
+    return value;
+  }
+  return DEFAULTS.severity;
+}
+
+function normalizeWaitMode(value: unknown): WaitMode {
+  if (value === "checks-finished") return "checks-finished";
+  return DEFAULTS.waitMode;
+}
+
+function clampPositiveNumber(
+  value: unknown,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(min, Math.min(max, Math.round(value)));
+}
+
+function normalizeRepo(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const repo = value.trim();
+  if (!repo) return undefined;
+  return repo;
+}
+
+async function ensureGhAvailable(pi: ExtensionAPI): Promise<void> {
+  const result = await exec(pi, "gh", ["--version"], EXEC_TIMEOUT_MS);
+  if (result.code !== 0) {
+    throw new Error("gh CLI is required. Install gh and run `gh auth login`.");
+  }
+}
+
+async function resolveRepo(pi: ExtensionAPI, repo?: string): Promise<string> {
+  if (repo) return repo;
+  const resolved = await ghText(pi, [
+    "repo",
+    "view",
+    "--json",
+    "nameWithOwner",
+    "-q",
+    ".nameWithOwner",
+  ]);
+  if (!resolved) {
+    throw new Error("cannot determine repo — pass repo as owner/repo");
+  }
+  return resolved;
+}
+
+async function resolvePrNumber(
+  pi: ExtensionAPI,
+  repo: string,
+  prNumber?: number,
+): Promise<number> {
+  if (prNumber && prNumber > 0) return prNumber;
+  const resolved = await ghText(pi, [
+    "pr",
+    "view",
+    "-R",
+    repo,
+    "--json",
+    "number",
+    "-q",
+    ".number",
+  ]);
+  const num = Number.parseInt(resolved, 10);
+  if (!Number.isInteger(num) || num <= 0) {
+    throw new Error("no PR for current branch — pass a PR number");
+  }
+  return num;
+}
+
+async function waitForNewReviewActivity(
+  pi: ExtensionAPI,
+  repo: string,
+  prNumber: number,
+  options: FindingsOptions,
+): Promise<boolean> {
+  const baseline = await fetchActivitySnapshot(pi, repo, prNumber);
+  const deadline = Date.now() + options.waitTimeoutSec * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(options.waitPollSec * 1000);
+    const current = await fetchActivitySnapshot(pi, repo, prNumber);
+    if (hasNewActivity(current, baseline)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function waitForChecksFinished(
+  pi: ExtensionAPI,
+  repo: string,
+  prNumber: number,
+  options: FindingsOptions,
+): Promise<boolean> {
+  const deadline = Date.now() + options.waitTimeoutSec * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(options.waitPollSec * 1000);
+    const checks = await fetchChecks(pi, repo, prNumber);
+    if (allChecksTerminal(checks)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function hasNewActivity(
+  current: ActivitySnapshot,
+  baseline: ActivitySnapshot,
+): boolean {
+  if (current.summaryCount > baseline.summaryCount) return true;
+  if (current.inlineCount > baseline.inlineCount) return true;
+  if (current.latestAtMs > baseline.latestAtMs) return true;
+  return false;
+}
+
+async function fetchActivitySnapshot(
+  pi: ExtensionAPI,
+  repo: string,
+  prNumber: number,
+): Promise<ActivitySnapshot> {
+  const prView = await ghJson<{
+    comments?: Array<{ createdAt?: string }>;
+    reviews?: Array<{ submittedAt?: string }>;
+  }>(pi, [
+    "pr",
+    "view",
+    String(prNumber),
+    "-R",
+    repo,
+    "--json",
+    "comments,reviews",
+  ]);
+
+  const inline = await ghJson<Array<{ created_at?: string }>>(pi, [
+    "api",
+    "-H",
+    "Accept: application/vnd.github+json",
+    `repos/${repo}/pulls/${prNumber}/comments?per_page=100`,
+  ]);
+
+  const summaryTimes = [
+    ...(prView.comments ?? []).map((c) => c.createdAt ?? ""),
+    ...(prView.reviews ?? []).map((r) => r.submittedAt ?? ""),
+  ];
+  const inlineTimes = (inline ?? []).map((c) => c.created_at ?? "");
+  const latestAtMs = Math.max(
+    ...[...summaryTimes, ...inlineTimes].map((iso) => parseIsoToMs(iso)),
+    0,
+  );
+
+  return {
+    summaryCount:
+      (prView.comments ?? []).length + (prView.reviews ?? []).length,
+    inlineCount: (inline ?? []).length,
+    latestAtMs,
+  };
+}
+
+async function fetchFindingsData(
+  pi: ExtensionAPI,
+  repo: string,
+  prNumber: number,
+): Promise<FindingsData> {
+  const owner = repo.split("/")[0] ?? "";
+  const name = repo.split("/")[1] ?? "";
+  if (!owner || !name) {
+    throw new Error("repo must be owner/repo");
+  }
+
+  await ensureGhVersion(pi);
+
+  const prView = await ghJson<{
+    number: number;
+    state: string;
+    headRefOid: string;
+    url: string;
+    comments?: Array<{
+      id?: string;
+      author?: { login?: string };
+      createdAt?: string;
+      body?: string;
+      url?: string;
+    }>;
+    reviews?: Array<{
+      id?: string;
+      author?: { login?: string };
+      submittedAt?: string;
+      body?: string;
+      url?: string;
+    }>;
+    statusCheckRollup?: Array<{
+      name?: string;
+      context?: string;
+      conclusion?: string;
+      state?: string;
+      detailsUrl?: string;
+      targetUrl?: string;
+    }>;
+  }>(pi, [
+    "pr",
+    "view",
+    String(prNumber),
+    "-R",
+    repo,
+    "--json",
+    "number,state,headRefOid,url,comments,reviews,statusCheckRollup",
+  ]);
+
+  const inline = await ghJson<
+    Array<{
+      id?: number;
+      user?: { login?: string };
+      created_at?: string;
+      path?: string;
+      line?: number;
+      original_line?: number;
+      body?: string;
+      commit_id?: string;
+      html_url?: string;
+    }>
+  >(pi, [
+    "api",
+    "-H",
+    "Accept: application/vnd.github+json",
+    `repos/${owner}/${name}/pulls/${prNumber}/comments?per_page=100`,
+  ]);
+
+  const threads = await ghJson<{
+    data?: {
+      repository?: {
+        pullRequest?: {
+          reviewThreads?: {
+            nodes?: Array<{
+              isResolved?: boolean;
+              isOutdated?: boolean;
+              comments?: { nodes?: Array<{ databaseId?: number }> };
+            }>;
+          };
+        };
+      };
+    };
+  }>(pi, [
+    "api",
+    "graphql",
+    "-f",
+    "query=query($owner:String!,$name:String!,$num:Int!){repository(owner:$owner,name:$name){pullRequest(number:$num){reviewThreads(first:100){nodes{isResolved isOutdated comments(first:100){nodes{databaseId}}}}}}}",
+    "-F",
+    `owner=${owner}`,
+    "-F",
+    `name=${name}`,
+    "-F",
+    `num=${prNumber}`,
+  ]);
+
+  const viewerLogin = await ghText(pi, ["api", "user", "-q", ".login"]);
+
+  const resolvedMap = buildResolvedMap(threads);
+  const headSha = prView.headRefOid ?? "";
+
+  const summaryComments: PrSummaryComment[] = [
+    ...((prView.comments ?? []).map((c) => ({
+      id: String(c.id ?? ""),
+      author: c.author?.login ?? "unknown",
+      createdAt: c.createdAt ?? "",
+      body: c.body ?? "",
+      url: c.url ?? "",
+    })) as PrSummaryComment[]),
+    ...((prView.reviews ?? [])
+      .filter((r) => (r.body ?? "") !== "")
+      .map((r) => ({
+        id: String(r.id ?? ""),
+        author: r.author?.login ?? "unknown",
+        createdAt: r.submittedAt ?? "",
+        body: r.body ?? "",
+        url: r.url ?? "",
+      })) as PrSummaryComment[]),
+  ];
+
+  const inlineComments: InlineComment[] = (inline ?? []).map((c) => {
+    const id = String(c.id ?? "");
+    const resolved = resolvedMap[id] ?? {
+      isOutdated: false,
+      isResolved: false,
+    };
+    return {
+      id,
+      author: c.user?.login ?? "unknown",
+      createdAt: c.created_at ?? "",
+      path: c.path ?? "?",
+      line: c.line ?? c.original_line ?? null,
+      body: c.body ?? "",
+      commitId: c.commit_id ?? "",
+      url: c.html_url ?? "",
+      isOutdated:
+        resolved.isOutdated ||
+        Boolean((c.commit_id ?? "") && (c.commit_id ?? "") !== headSha),
+      isResolved: resolved.isResolved,
+    };
+  });
+
+  return {
+    pr: {
+      number: prView.number,
+      state: prView.state ?? "OPEN",
+      headSha,
+      url: prView.url ?? "",
+    },
+    viewerLogin,
+    checks: (prView.statusCheckRollup ?? []).map((check) => ({
+      name: check.name ?? check.context ?? "check",
+      conclusion: check.conclusion ?? check.state ?? "PENDING",
+      url: check.detailsUrl ?? check.targetUrl ?? "",
+    })),
+    summaryComments,
+    inlineComments,
+  };
+}
+
+function buildResolvedMap(threads: {
+  data?: {
+    repository?: {
+      pullRequest?: {
+        reviewThreads?: {
+          nodes?: Array<{
+            isResolved?: boolean;
+            isOutdated?: boolean;
+            comments?: { nodes?: Array<{ databaseId?: number }> };
+          }>;
+        };
+      };
+    };
+  };
+}): Record<string, { isResolved: boolean; isOutdated: boolean }> {
+  const out: Record<string, { isResolved: boolean; isOutdated: boolean }> = {};
+  const nodes =
+    threads.data?.repository?.pullRequest?.reviewThreads?.nodes ?? [];
+
+  for (const thread of nodes) {
+    const isResolved = thread.isResolved === true;
+    const isOutdated = thread.isOutdated === true;
+    for (const comment of thread.comments?.nodes ?? []) {
+      if (typeof comment.databaseId !== "number") continue;
+      out[String(comment.databaseId)] = { isResolved, isOutdated };
+    }
+  }
+
+  return out;
+}
+
+async function ensureGhVersion(pi: ExtensionAPI): Promise<void> {
+  const version = await ghText(pi, ["--version"]);
+  const firstLine = version.split("\n")[0] ?? "";
+  const raw = firstLine.split(" ")[2] ?? "";
+  const [majorText, minorText] = raw.split(".");
+  const major = Number.parseInt(majorText ?? "0", 10);
+  const minor = Number.parseInt(minorText ?? "0", 10);
+  if (major < 2 || (major === 2 && minor < 40)) {
+    throw new Error(
+      `gh ${raw || "unknown"} is too old — need >= 2.40 for statusCheckRollup`,
+    );
+  }
+}
+
+async function fetchChecks(
+  pi: ExtensionAPI,
+  repo: string,
+  prNumber: number,
+): Promise<Array<{ conclusion?: string; state?: string }>> {
+  const prView = await ghJson<{
+    statusCheckRollup?: Array<{ conclusion?: string; state?: string }>;
+  }>(pi, [
+    "pr",
+    "view",
+    String(prNumber),
+    "-R",
+    repo,
+    "--json",
+    "statusCheckRollup",
+  ]);
+
+  return prView.statusCheckRollup ?? [];
+}
+
+function allChecksTerminal(
+  checks: Array<{ conclusion?: string; state?: string }>,
+): boolean {
+  if (checks.length === 0) return true;
+  return checks.every((check) => {
+    const value = (check.conclusion ?? check.state ?? "").toUpperCase();
+    return ![
+      "PENDING",
+      "IN_PROGRESS",
+      "QUEUED",
+      "WAITING",
+      "REQUESTED",
+    ].includes(value);
+  });
+}
+
+function renderMarkdown(data: FindingsData, options: FindingsOptions): string {
+  const findings: Record<"blocker" | "warning" | "nit" | "info", string[]> = {
+    blocker: [],
+    warning: [],
+    nit: [],
+    info: [],
+  };
+
+  let staleDropped = 0;
+
+  const keep = (author: string, isResolved?: boolean): boolean => {
+    const lower = author.toLowerCase();
+    if (DROP_AUTHORS.has(lower)) return false;
+    if (options.mine && lower !== data.viewerLogin.toLowerCase()) return false;
+    if (options.unresolved && isResolved) return false;
+    return true;
+  };
+
+  for (const c of data.inlineComments) {
+    if (!keep(c.author, c.isResolved)) continue;
+    if (c.isOutdated && !options.includeStale) {
+      staleDropped += 1;
+      continue;
+    }
+    const sev = classify(c.body);
+    const lineNo = c.line ?? "?";
+    findings[sev].push(
+      `- \`${c.path}:${lineNo}\` — ${excerpt(c.body)} ([link](${c.url}))`,
+    );
+  }
+
+  for (const c of data.summaryComments) {
+    if (!keep(c.author, false)) continue;
+
+    const split = splitBotSummary(c.body);
+    if (split) {
+      for (const part of split) {
+        findings[part.severity].push(
+          `- _${c.author}_: ${excerpt(part.item)} ([link](${c.url}))`,
+        );
+      }
+      continue;
+    }
+
+    const sev = classify(c.body);
+    findings[sev].push(
+      `- _${c.author}_ (${humanizeAge(c.createdAt)}): ${excerpt(c.body)} ([link](${c.url}))`,
+    );
+  }
+
+  if (options.severity !== "all") {
+    for (const key of Object.keys(findings) as Array<
+      "blocker" | "warning" | "nit" | "info"
+    >) {
+      if (key !== options.severity) findings[key] = [];
+    }
+  }
+
+  const shortSha = data.pr.headSha.slice(0, 7);
+  const parts: string[] = [];
+  parts.push(
+    `## PR #${data.pr.number} findings — revision \`${shortSha}\` ${stateBadge(data.pr.state)}`.trim(),
+  );
+
+  if (data.checks.length > 0) {
+    const renderedChecks = data.checks
+      .map((check) => {
+        const failed = ["FAILURE", "ERROR"].includes(
+          (check.conclusion ?? "").toUpperCase(),
+        );
+        const details = failed && check.url ? ` ([details](${check.url}))` : "";
+        return `${checkIcon(check.conclusion)} ${check.name}${details}`;
+      })
+      .join(" · ");
+    parts.push(`\n**Status checks:** ${renderedChecks}`);
+  }
+
+  const sections: Array<[keyof typeof findings, string]> = [
+    ["blocker", "### 🔴 Blockers"],
+    ["warning", "### 🟡 Warnings"],
+    ["nit", "### 🔵 Nits"],
+    ["info", "### ✅ Approvals / strengths"],
+  ];
+
+  for (const [key, header] of sections) {
+    const items = findings[key];
+    if (items.length === 0) continue;
+    parts.push(`\n${header} (${items.length})\n`);
+    parts.push(...items);
+  }
+
+  if (staleDropped > 0 && !options.includeStale) {
+    parts.push(
+      `\n---\n<small>${staleDropped} stale finding(s) on older commits skipped (use \`--include-stale\` to show).</small>`,
+    );
+  }
+
+  const total = Object.values(findings).reduce(
+    (sum, items) => sum + items.length,
+    0,
+  );
+  if (total === 0) {
+    parts.push("\n_No findings._");
+  }
+
+  return `${parts.join("\n")}\n`;
+}
+
+function classify(body: string): "blocker" | "warning" | "nit" | "info" {
+  const text = body.toLowerCase();
+
+  if (matchesAny(text, ["🔴", "blocker", "must fix", "critical", "breaks"])) {
+    return "blocker";
+  }
+  if (
+    matchesAny(text, ["🟡", "warning", "should", "leak", "race", "missing"])
+  ) {
+    return "warning";
+  }
+  if (
+    matchesAny(text, [
+      "🔵",
+      "nit",
+      "suggestion",
+      "consider",
+      "could be",
+      "minor",
+    ])
+  ) {
+    return "nit";
+  }
+  if (matchesAny(text, ["approved", "lgtm", "strength", "looks good"])) {
+    return "info";
+  }
+
+  return "warning";
+}
+
+function matchesAny(text: string, patterns: string[]): boolean {
+  return patterns.some((pattern) => {
+    if (
+      pattern.length === 1 ||
+      pattern.includes("🔴") ||
+      pattern.includes("🟡") ||
+      pattern.includes("🔵")
+    ) {
+      return text.includes(pattern.toLowerCase());
+    }
+    return new RegExp(`\\b${escapeRegex(pattern)}\\b`, "i").test(text);
+  });
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function splitBotSummary(body: string): Array<{
+  severity: "blocker" | "warning" | "nit" | "info";
+  item: string;
+}> | null {
+  const sectionHeaderRe = new RegExp(
+    SECTION_HEADER_RE.source,
+    SECTION_HEADER_RE.flags,
+  );
+  const matches = Array.from(body.matchAll(sectionHeaderRe));
+  if (matches.length === 0) return null;
+
+  const out: Array<{
+    severity: "blocker" | "warning" | "nit" | "info";
+    item: string;
+  }> = [];
+
+  for (let i = 0; i < matches.length; i += 1) {
+    const current = matches[i];
+    const section = current?.[1] ?? "";
+    const start =
+      current?.index !== undefined ? current.index + current[0].length : 0;
+    const end =
+      i + 1 < matches.length && matches[i + 1]?.index !== undefined
+        ? (matches[i + 1]?.index as number)
+        : body.length;
+
+    const sectionBody = body.slice(start, end).trim();
+    const severity = sectionToSeverity(section);
+    const items = sectionBody
+      .split(NUMBERED_ITEM_RE)
+      .map((item) => item.trim())
+      .filter(Boolean);
+
+    if (items.length === 0) {
+      if (sectionBody) out.push({ severity, item: sectionBody });
+      continue;
+    }
+
+    for (const item of items) {
+      out.push({ severity, item });
+    }
+  }
+
+  return out.length > 0 ? out : null;
+}
+
+function sectionToSeverity(
+  section: string,
+): "blocker" | "warning" | "nit" | "info" {
+  const value = section.toLowerCase();
+  if (value.includes("blocker")) return "blocker";
+  if (value.includes("warning")) return "warning";
+  if (value.includes("nit") || value.includes("suggestion")) return "nit";
+  if (value.includes("approval") || value.includes("strength")) return "info";
+  return "warning";
+}
+
+function parseIsoToMs(iso: string): number {
+  if (!iso) return 0;
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? ms : 0;
+}
+
+function humanizeAge(iso: string): string {
+  const ms = parseIsoToMs(iso);
+  if (ms <= 0) return "";
+  const secs = Math.max(0, Math.floor((Date.now() - ms) / 1000));
+  if (secs < 60) return `${secs}s ago`;
+  if (secs < 3600) return `${Math.floor(secs / 60)}m ago`;
+  if (secs < 86400) return `${Math.floor(secs / 3600)}h ago`;
+  return `${Math.floor(secs / 86400)}d ago`;
+}
+
+function excerpt(body: string, limit = 200): string {
+  const text = body.split(/\s+/).filter(Boolean).join(" ");
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit - 1)}…`;
+}
+
+function checkIcon(conclusion: string): string {
+  const value = (conclusion || "").toUpperCase();
+  const map: Record<string, string> = {
+    SUCCESS: "✅",
+    FAILURE: "❌",
+    ERROR: "❌",
+    CANCELLED: "⚪",
+    SKIPPED: "⚪",
+    PENDING: "⏳",
+    IN_PROGRESS: "⏳",
+    NEUTRAL: "➖",
+  };
+  return map[value] ?? "❓";
+}
+
+function stateBadge(state: string): string {
+  const value = (state || "").toUpperCase();
+  if (value === "OPEN" || !value) return "";
+  return `_(PR is ${value})_`;
+}
+
+function closingLine(report: string): string {
+  if (report.includes("### 🔴 Blockers")) {
+    return "Address blockers before merge.";
+  }
+  if (report.includes("### 🟡 Warnings")) {
+    return "Review warnings before merge.";
+  }
+  if (report.includes("### 🔵 Nits")) {
+    return "Nits only — safe to merge if you skip them.";
+  }
+  return "No unresolved findings remain.";
+}
+
+async function ghText(pi: ExtensionAPI, args: string[]): Promise<string> {
+  const result = await exec(pi, "gh", args, EXEC_TIMEOUT_MS);
+  if (result.code !== 0) {
+    throw new Error(formatGhError(result));
+  }
+  return result.stdout?.trim() ?? "";
+}
+
+async function ghJson<T>(pi: ExtensionAPI, args: string[]): Promise<T> {
+  const result = await exec(pi, "gh", args, EXEC_TIMEOUT_MS);
+  if (result.code !== 0) {
+    throw new Error(formatGhError(result));
+  }
+
+  const text = result.stdout?.trim() ?? "";
+  if (!text) {
+    throw new Error("gh returned empty response");
+  }
+
+  try {
+    return JSON.parse(text) as T;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`invalid gh JSON response: ${message}`);
+  }
+}
+
+function formatGhError(result: ExecResult): string {
+  const raw = (
+    result.stderr?.trim() ||
+    result.stdout?.trim() ||
+    "gh command failed"
+  ).trim();
+  if (raw.includes("authentication") || raw.includes("gh auth login")) {
+    return "gh is not authenticated. Run `gh auth login`.";
+  }
+  return raw;
+}
+
+async function exec(
+  pi: ExtensionAPI,
+  command: string,
+  args: string[],
+  timeoutMs: number,
+): Promise<ExecResult> {
+  return pi.exec(command, args, { timeout: timeoutMs });
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@testzugang/pi-pr-findings",
+  "version": "0.1.0",
+  "description": "Fetch and group GitHub PR review findings by severity in Pi",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "skills",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/pr-findings/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: pr-findings
+description: Use when the user asks for GitHub PR review findings, review comments, unresolved findings, bot feedback, or reviewer feedback grouped by severity.
+---
+
+# PR Findings
+
+## Goal
+
+Fetch GitHub PR review findings through the `pr_findings` tool (backed by `gh`), format by severity, and print the tool output verbatim.
+
+## Inputs
+
+Infer from the user request (or `/skill:pr-findings ...` args):
+
+- PR number (optional)
+- Repository `owner/repo` (optional)
+- `--unresolved`
+- `--severity blocker|warning|nit|all`
+- `--include-stale`
+- `--mine`
+- `--wait-for-next-review` (optional)
+- `--wait-timeout-sec <n>` (default 60)
+- `--wait-poll-sec <n>` (default 30)
+
+## Workflow
+
+1. Build tool params from user input.
+2. Call `pr_findings`.
+3. Print returned Markdown verbatim (do not paraphrase).
+
+## Tool Call
+
+```text
+pr_findings({
+  prNumber?: number,
+  repo?: "owner/repo",
+  unresolved?: boolean,
+  severity?: "blocker" | "warning" | "nit" | "all",
+  includeStale?: boolean,
+  mine?: boolean,
+  waitForNextReview?: boolean,
+  waitMode?: "new-review-activity" | "checks-finished",
+  waitTimeoutSec?: number,
+  waitPollSec?: number
+})
+```
+
+Default wait behavior when enabled:
+
+- `waitMode="new-review-activity"`
+- `waitTimeoutSec=60`
+- `waitPollSec=30`
+
+## Recommended Usage After Push
+
+Use waiting mode after pushing fixes so findings are not read too early:
+
+```text
+pr_findings({ waitForNextReview: true, unresolved: true })
+```
+
+## Edge Cases
+
+| Situation                   | Response                                                   |
+| --------------------------- | ---------------------------------------------------------- |
+| `gh` not authenticated      | Tell the user to run `gh auth login`.                      |
+| No PR for current branch    | Ask for a PR number.                                       |
+| Cannot determine repository | Ask for `owner/repo`.                                      |
+| PR is closed or merged      | Still fetch findings; report includes PR state.            |
+| `gh` too old                | Surface error requiring `gh >= 2.40`.                      |
+| Wait timed out              | Report that timeout was reached and show current findings. |

package/skills/pr-findings/fetch.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PR_NUMBER="${1:?PR number required}"
+REPO="${2:-$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || true)}"
+
+if [[ -z "${REPO}" ]]; then
+  echo "fetch.sh: cannot determine repo — pass <owner/repo> as second argument" >&2
+  exit 2
+fi
+
+OWNER="${REPO%/*}"
+NAME="${REPO#*/}"
+
+GH_VERSION="$(gh --version | head -n1 | awk '{print $3}')"
+GH_MAJOR="${GH_VERSION%%.*}"
+GH_REST="${GH_VERSION#*.}"
+GH_MINOR="${GH_REST%%.*}"
+if (( GH_MAJOR < 2 )) || { (( GH_MAJOR == 2 )) && (( GH_MINOR < 40 )); }; then
+  echo "fetch.sh: gh ${GH_VERSION} is too old — need >= 2.40 for statusCheckRollup" >&2
+  exit 3
+fi
+
+PR_VIEW=$(gh pr view "$PR_NUMBER" -R "$REPO" \
+  --json number,state,headRefOid,url,comments,reviews,statusCheckRollup)
+
+INLINE=$(gh api --paginate -H "Accept: application/vnd.github+json" \
+  "repos/$OWNER/$NAME/pulls/$PR_NUMBER/comments?per_page=100")
+
+THREADS=$(gh api graphql -f query='
+  query($owner:String!,$name:String!,$num:Int!){
+    repository(owner:$owner,name:$name){
+      pullRequest(number:$num){
+        reviewThreads(first:100){
+          nodes{ isResolved isOutdated comments(first:100){ nodes{ databaseId } } }
+        }
+      }
+    }
+  }' -F owner="$OWNER" -F name="$NAME" -F num="$PR_NUMBER")
+
+VIEWER=$(gh api user -q .login)
+
+RESOLVED_MAP=$(echo "$THREADS" | jq -c '
+  [.data.repository.pullRequest.reviewThreads.nodes[]
+    | . as $t
+    | $t.comments.nodes[]
+    | { key: (.databaseId|tostring),
+        value: { isResolved: $t.isResolved, isOutdated: $t.isOutdated } }
+  ] | from_entries')
+
+HEAD_SHA=$(echo "$PR_VIEW" | jq -r .headRefOid)
+
+jq -n \
+  --argjson pr "$PR_VIEW" \
+  --argjson inline "$INLINE" \
+  --argjson resolved "$RESOLVED_MAP" \
+  --arg viewer "$VIEWER" \
+  --arg head "$HEAD_SHA" \
+  '{
+     pr: { number: $pr.number, state: $pr.state, headSha: $head, url: $pr.url },
+     viewerLogin: $viewer,
+     checks: ($pr.statusCheckRollup // [] | map({ name: (.name // .context // "check"), conclusion: (.conclusion // .state // "PENDING"), url: (.detailsUrl // .targetUrl // "") })),
+     summaryComments: (
+       ($pr.comments // [] | map({
+         id: (.id|tostring), author: (.author.login // "unknown"),
+         createdAt: .createdAt, body: .body, url: (.url // "")
+       }))
+       +
+       ($pr.reviews // [] | map(select((.body // "") != "")) | map({
+         id: (.id|tostring), author: (.author.login // "unknown"),
+         createdAt: .submittedAt, body: .body, url: (.url // "")
+       }))
+     ),
+     inlineComments: ($inline | map({
+       id: (.id|tostring),
+       author: (.user.login // "unknown"),
+       createdAt: .created_at,
+       path: .path,
+       line: (.line // .original_line),
+       body: .body,
+       commitId: .commit_id,
+       url: .html_url,
+       isOutdated: ($resolved[(.id|tostring)].isOutdated // ((.commit_id // "") != $head)),
+       isResolved: ($resolved[(.id|tostring)].isResolved // false)
+     }))
+   }'

package/skills/pr-findings/format.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Read fetch.sh JSON on stdin, emit a Markdown findings report on stdout."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+
+DROP_AUTHORS = {"sonarqubecloud[bot]", "sonarcloud[bot]", "dependabot[bot]", "github-actions[bot]"}
+
+SEVERITY_PATTERNS = [
+    ("blocker", [r"🔴", r"\bblocker\b", r"\bmust fix\b", r"\bcritical\b", r"\bbreaks\b"]),
+    ("warning", [r"🟡", r"\bwarning\b", r"\bshould\b", r"\bleak\b", r"\brace\b", r"\bmissing\b"]),
+    ("nit",     [r"🔵", r"\bnit\b", r"\bsuggestion\b", r"\bconsider\b", r"\bcould be\b", r"\bminor\b"]),
+    ("info",    [r"\bapproved\b", r"\blgtm\b", r"\bstrength\b", r"\blooks good\b"]),
+]
+
+SECTION_HEADER_RE = re.compile(
+    r"^#{1,6}\s*(?:🔴|🟡|🔵|✅)?\s*(blockers?|warnings?|nits?|approvals?|strengths?|suggestions?).*$",
+    re.IGNORECASE | re.MULTILINE,
+)
+NUMBERED_ITEM_RE = re.compile(r"^\s*\d+\.\s+", re.MULTILINE)
+
+
+def classify(body: str) -> str:
+    text = body.lower()
+    for sev, patterns in SEVERITY_PATTERNS:
+        for p in patterns:
+            if re.search(p, text):
+                return sev
+    return "warning"
+
+
+def section_to_severity(section: str) -> str:
+    s = section.lower()
+    if "blocker" in s:
+        return "blocker"
+    if "warning" in s:
+        return "warning"
+    if "nit" in s or "suggestion" in s:
+        return "nit"
+    if "approval" in s or "strength" in s:
+        return "info"
+    return "warning"
+
+
+def split_bot_summary(body: str) -> list[tuple[str, str]] | None:
+    """If the comment has section headers like '### 🟡 Warnings', split into (severity, item) tuples."""
+    matches = list(SECTION_HEADER_RE.finditer(body))
+    if not matches:
+        return None
+    out: list[tuple[str, str]] = []
+    for i, m in enumerate(matches):
+        sev = section_to_severity(m.group(1))
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(body)
+        section_body = body[start:end].strip()
+        items = NUMBERED_ITEM_RE.split(section_body)
+        items = [it.strip() for it in items if it.strip()]
+        if not items:
+            if section_body:
+                out.append((sev, section_body))
+            continue
+        for item in items:
+            out.append((sev, item))
+    return out or None
+
+
+def humanize_age(iso: str) -> str:
+    if not iso:
+        return ""
+    try:
+        dt = datetime.fromisoformat(iso.replace("Z", "+00:00"))
+    except ValueError:
+        return iso
+    delta = datetime.now(timezone.utc) - dt
+    secs = int(delta.total_seconds())
+    if secs < 60:
+        return f"{secs}s ago"
+    if secs < 3600:
+        return f"{secs // 60}m ago"
+    if secs < 86400:
+        return f"{secs // 3600}h ago"
+    return f"{secs // 86400}d ago"
+
+
+def excerpt(body: str, limit: int = 200) -> str:
+    text = " ".join(body.split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def check_icon(conclusion: str) -> str:
+    c = (conclusion or "").upper()
+    return {
+        "SUCCESS": "✅",
+        "FAILURE": "❌",
+        "ERROR": "❌",
+        "CANCELLED": "⚪",
+        "SKIPPED": "⚪",
+        "PENDING": "⏳",
+        "IN_PROGRESS": "⏳",
+        "NEUTRAL": "➖",
+    }.get(c, "❓")
+
+
+def state_badge(state: str) -> str:
+    s = (state or "").upper()
+    if s == "OPEN":
+        return ""
+    return f"_(PR is {s})_"
+
+
+def render(data: dict, args: argparse.Namespace) -> str:
+    pr = data.get("pr", {})
+    viewer = data.get("viewerLogin", "")
+    checks = data.get("checks", []) or []
+    summary_comments = data.get("summaryComments", []) or []
+    inline_comments = data.get("inlineComments", []) or []
+
+    findings: dict[str, list[str]] = {"blocker": [], "warning": [], "nit": [], "info": []}
+    stale_dropped = 0
+
+    def keep(c: dict) -> bool:
+        author = (c.get("author") or "").lower()
+        if author in DROP_AUTHORS:
+            return False
+        if args.mine and author != (viewer or "").lower():
+            return False
+        if args.unresolved and c.get("isResolved"):
+            return False
+        return True
+
+    # Inline comments
+    for c in inline_comments:
+        if not keep(c):
+            continue
+        if c.get("isOutdated") and not args.include_stale:
+            stale_dropped += 1
+            continue
+        sev = classify(c.get("body", ""))
+        loc = f"`{c.get('path','?')}:{c.get('line','?')}`"
+        line = f"- {loc} — {excerpt(c.get('body',''))} ([link]({c.get('url','')}))"
+        findings[sev].append(line)
+
+    # Summary/review comments — bots may pack multiple findings into one
+    for c in summary_comments:
+        if not keep(c):
+            continue
+        body = c.get("body", "")
+        author = c.get("author", "?")
+        url = c.get("url", "")
+        split = split_bot_summary(body)
+        if split:
+            for sev, item in split:
+                line = f"- _{author}_: {excerpt(item)} ([link]({url}))"
+                findings[sev].append(line)
+        else:
+            sev = classify(body)
+            line = f"- _{author}_ ({humanize_age(c.get('createdAt',''))}): {excerpt(body)} ([link]({url}))"
+            findings[sev].append(line)
+
+    # Severity filter
+    if args.severity != "all":
+        for sev in list(findings.keys()):
+            if sev != args.severity:
+                findings[sev] = []
+
+    # Header
+    short_sha = (pr.get("headSha") or "")[:7]
+    parts: list[str] = []
+    parts.append(f"## PR #{pr.get('number','?')} findings — revision `{short_sha}` {state_badge(pr.get('state',''))}".rstrip())
+
+    if checks:
+        rendered_checks = " · ".join(
+            f"{check_icon(ch.get('conclusion',''))} {ch.get('name','?')}"
+            + (f" ([details]({ch['url']}))" if ch.get("conclusion","").upper() in {"FAILURE","ERROR"} and ch.get("url") else "")
+            for ch in checks
+        )
+        parts.append(f"\n**Status checks:** {rendered_checks}")
+
+    section_headers = [
+        ("blocker", "### 🔴 Blockers"),
+        ("warning", "### 🟡 Warnings"),
+        ("nit",     "### 🔵 Nits"),
+        ("info",    "### ✅ Approvals / strengths"),
+    ]
+    for key, header in section_headers:
+        items = findings[key]
+        if not items:
+            continue
+        parts.append(f"\n{header} ({len(items)})\n")
+        parts.extend(items)
+
+    if stale_dropped and not args.include_stale:
+        parts.append(f"\n---\n<small>{stale_dropped} stale finding(s) on older commits skipped (use `--include-stale` to show).</small>")
+
+    total = sum(len(v) for v in findings.values())
+    if total == 0:
+        parts.append("\n_No findings._")
+
+    return "\n".join(parts) + "\n"
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--severity", choices=["blocker", "warning", "nit", "all"], default="all")
+    p.add_argument("--unresolved", action="store_true")
+    p.add_argument("--include-stale", action="store_true")
+    p.add_argument("--mine", action="store_true")
+    args = p.parse_args()
+
+    raw = sys.stdin.read()
+    if not raw.strip():
+        print("format.py: empty input on stdin", file=sys.stderr)
+        return 2
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(f"format.py: invalid JSON on stdin: {e}", file=sys.stderr)
+        return 2
+
+    sys.stdout.write(render(data, args))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())