@usepipr/runtime 0.3.1 → 0.3.3

package/dist/{commands-BNxl37V6.mjs → commands-C1sVsbEj.mjs}

@@ -768,13 +768,11 @@ export default definePipr((pipr) => {
       const result = await ctx.pi.run(changelog, { manifest });
       await ctx.comment(
         [
-          "## Changelog Draft",
-          "",
           \`**Category:** \${result.category}\`,
           "",
           result.entry,
           "",
-          "### Rationale",
+          "## Rationale",
           result.rationale,
         ].join("\\n"),
       );
@@ -869,23 +867,36 @@ export default definePipr((pipr) => {
       Return only actionable findings that target valid diff ranges.
     \`,
     timeout: "10m",
-    comment: (result, context) => ({
-      main:
-        context.platform.id === "local"
-          ? [
-              "## Summary",
-              "",
-              result.summary.body,
-              "",
-              "## Inline Findings",
-              "",
-              result.inlineFindings.length === 0
-                ? "No inline findings."
-                : result.inlineFindings.map((finding) => \`- \${finding.body}\`).join("\\n"),
-            ].join("\\n")
-          : result.summary.body,
-      inlineFindings: result.inlineFindings,
-    }),
+    comment: (result, context) => {
+      const inlineFindingSummary =
+        result.inlineFindings.length === 0
+          ? "No inline findings."
+          : "See inline comments in the diff.";
+      const localInlineFindingSummary = [
+        "## Inline Findings",
+        "",
+        result.inlineFindings.length === 0
+          ? "No inline findings."
+          : result.inlineFindings.map((finding) => \`- \${finding.body}\`).join("\\n"),
+      ].join("\\n");
+
+      return {
+        main: [
+          "## Summary",
+          "",
+          result.summary.body,
+          "",
+          "## Review Result",
+          "",
+          "| Signal | Result |",
+          "| --- | ---: |",
+          \`| Inline findings | \${result.inlineFindings.length} |\`,
+          "",
+          context.platform.id === "local" ? localInlineFindingSummary : inlineFindingSummary,
+        ].join("\\n"),
+        inlineFindings: result.inlineFindings,
+      };
+    },
   });
 });
 `
@@ -948,20 +959,18 @@ export default definePipr((pipr) => {
       };
       const manifest = await ctx.change.diffManifest({ compressed: true, paths });
       if (manifest.files.length === 0) {
-        await ctx.comment("## Dependency Risk\\n\\nNo dependency files changed.");
+        await ctx.comment("No dependency files changed.");
         return;
       }
       const result = await ctx.pi.run(dependencyReviewer, { manifest }, { paths });
       await ctx.comment(
         [
-          "## Dependency Risk",
-          "",
           result.summary,
           "",
-          "### Risks",
+          "## Risks",
           ...result.risks.map((risk) => \`- \${risk}\`),
           "",
-          "### Follow-ups",
+          "## Follow-ups",
           ...result.followUps.map((followUp) => \`- \${followUp}\`),
         ].join("\\n"),
       );
@@ -1033,7 +1042,7 @@ export default definePipr((pipr) => {
         ...(diagnostic.suggestedFix ? { suggestedFix: diagnostic.suggestedFix } : {}),
       }));
       await ctx.comment({
-        main: \`## Diff Diagnostics\\n\\n\${result.summary}\`,
+        main: result.summary,
         inlineFindings,
       });
     },
@@ -1045,6 +1054,268 @@ export default definePipr((pipr) => {
 `
 };
 //#endregion
+//#region src/config/recipes/fix-suggestions.ts
+const fixSuggestionsRecipe = {
+	id: "fix-suggestions",
+	title: "Fix Suggestions",
+	description: "Command-first exact suggested fixes for actionable review improvements.",
+	sourceTools: [
+		"Qodo Merge /improve",
+		"GitHub Copilot code review",
+		"Cursor Bugbot"
+	],
+	configTs: `import { definePipr, z } from "@usepipr/sdk";
+import type { CommentableRange, DiffManifest, ReviewFinding } from "@usepipr/sdk";
+
+export default definePipr((pipr) => {
+  const model = pipr.model({
+    provider: "deepseek",
+    model: "deepseek-v4-pro",
+    apiKey: pipr.secret({ name: "DEEPSEEK_API_KEY" }),
+    options: { thinking: "high" },
+  });
+
+  pipr.config({ publication: { maxInlineComments: 6 } });
+
+  const fixSuggestionSchema = z.strictObject({
+    title: z.string(),
+    category: z.enum(["correctness", "tests", "maintainability", "typing", "documentation"]),
+    body: z.string(),
+    path: z.string(),
+    rangeId: z.string(),
+    side: z.enum(["RIGHT", "LEFT"]),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+    suggestedFix: z.string().min(1),
+  });
+
+  type FixSuggestion = z.infer<typeof fixSuggestionSchema>;
+
+  const fixSuggestionOutput = pipr.schema({
+    id: "review/fix-suggestions",
+    schema: z.strictObject({
+      summary: z.string(),
+      suggestions: z.array(fixSuggestionSchema),
+    }),
+  });
+
+  const fixer = pipr.agent({
+    name: "fix-suggestions",
+    model,
+    instructions: \`
+      Find exact suggested changes for this pull request. Return a suggestion only
+      when suggestedFix is a precise replacement for the selected diff range and
+      the reviewer can apply it directly. Prioritize correctness, missing tests,
+      type safety, and small maintainability improvements. Do not report broad
+      refactors, style preferences, or issues without an exact patch.
+    \`,
+    output: fixSuggestionOutput,
+    tools: pipr.tools.readOnly,
+    retry: { invalidOutput: 1, transientFailure: 1 },
+    timeout: "7m",
+    prompt: () => "Find exact suggested changes for this pull request.",
+  });
+
+  const task = pipr.task({
+    name: "fix-suggestions",
+    async run(ctx) {
+      if (!ctx.command) {
+        throw new Error("fix-suggestions is a command-only task");
+      }
+      const manifest = await ctx.change.diffManifest({ compressed: true });
+      const result = await ctx.pi.run(fixer, { manifest });
+      const publishableSuggestions = result.suggestions.filter(
+        (suggestion) => isPublishableSuggestion(suggestion, manifest),
+      );
+      const inlineFindings: ReviewFinding[] = publishableSuggestions.map((suggestion) => {
+        const category = suggestion.category
+          .replaceAll("-", " ")
+          .replace(/^./, (char) => char.toUpperCase());
+        return {
+          body: \`**\${category}:** \${suggestion.title}. \${suggestion.body}\`,
+          path: suggestion.path,
+          rangeId: suggestion.rangeId,
+          side: suggestion.side,
+          startLine: suggestion.startLine,
+          endLine: suggestion.endLine,
+          suggestedFix: suggestion.suggestedFix,
+        };
+      });
+      await ctx.comment({
+        main: [
+          result.summary,
+          "",
+          "## Exact Suggested Changes",
+          "",
+          suggestionsTable(publishableSuggestions),
+        ].join("\\n"),
+        inlineFindings,
+      });
+    },
+  });
+
+  pipr.command({
+    pattern: "@pipr improve",
+    permission: "write",
+    description: "Find exact suggested fixes for this pull request.",
+    task,
+  });
+});
+
+type FindingAnchor = Pick<ReviewFinding, "path" | "rangeId" | "side" | "startLine" | "endLine">;
+
+function isPublishableSuggestion(suggestion: FixSuggestion, manifest: DiffManifest): boolean {
+  if (suggestion.suggestedFix.trim().length === 0) {
+    return false;
+  }
+  const range = commentableRangeForFinding(suggestion, manifest);
+  return Boolean(
+    range &&
+      isPublishableSuggestedFixSelection({
+        side: suggestion.side,
+        kind: range.kind,
+        rangeStartLine: range.startLine,
+        startLine: suggestion.startLine,
+        endLine: suggestion.endLine,
+        preview: range.preview,
+        suggestedFix: suggestion.suggestedFix,
+      }),
+  );
+}
+
+function commentableRangeForFinding(
+  finding: FindingAnchor,
+  manifest: DiffManifest,
+): CommentableRange | undefined {
+  for (const file of manifest.files) {
+    const range = file.commentableRanges.find((candidate) => candidate.id === finding.rangeId);
+    if (!range) {
+      continue;
+    }
+    return finding.rangeId === range.id &&
+      finding.path === range.path &&
+      finding.side === range.side &&
+      finding.startLine <= finding.endLine &&
+      finding.startLine >= range.startLine &&
+      finding.endLine <= range.endLine
+      ? range
+      : undefined;
+  }
+  return undefined;
+}
+
+function isPublishableSuggestedFixSelection(selection: {
+  side: "RIGHT" | "LEFT";
+  kind: "added" | "deleted" | "context" | "mixed";
+  rangeStartLine: number;
+  startLine: number;
+  endLine: number;
+  preview?: string;
+  suggestedFix: string;
+}): boolean {
+  const suggestedLines = normalizedSuggestedFixLines(selection.suggestedFix);
+  const selectedLineCount = selection.endLine - selection.startLine + 1;
+  if (
+    selection.side !== "RIGHT" ||
+    selection.kind === "deleted" ||
+    selectedLineCount > 12 ||
+    suggestedLines.length > 20
+  ) {
+    return false;
+  }
+
+  const originalLines = selectedPreviewLines(selection, selectedLineCount);
+  return Boolean(
+    originalLines &&
+      !hasUnchangedSelectionEdge(originalLines, suggestedLines) &&
+      !suggestionIncludesUnselectedContext(selection, selectedLineCount, suggestedLines),
+  );
+}
+
+function normalizedSuggestedFixLines(value: string): string[] {
+  const normalized = value.replace(/\\r\\n/g, "\\n").replace(/\\r/g, "\\n");
+  const withoutFinalNewline = normalized.endsWith("\\n") ? normalized.slice(0, -1) : normalized;
+  return withoutFinalNewline.length === 0 ? [] : withoutFinalNewline.split("\\n");
+}
+
+function selectedPreviewLines(
+  selection: {
+    rangeStartLine: number;
+    startLine: number;
+    preview?: string;
+  },
+  selectedLineCount: number,
+): string[] | undefined {
+  if (!selection.preview) {
+    return undefined;
+  }
+  const offset = selection.startLine - selection.rangeStartLine;
+  if (offset < 0) {
+    return undefined;
+  }
+  const previewLines = selection.preview.replace(/\\r\\n/g, "\\n").replace(/\\r/g, "\\n").split("\\n");
+  if (offset + selectedLineCount > previewLines.length) {
+    return undefined;
+  }
+  return previewLines.slice(offset, offset + selectedLineCount);
+}
+
+function suggestionIncludesUnselectedContext(
+  selection: {
+    rangeStartLine: number;
+    startLine: number;
+    preview?: string;
+  },
+  selectedLineCount: number,
+  suggestedLines: string[],
+): boolean {
+  if (!selection.preview || suggestedLines.length <= selectedLineCount) {
+    return false;
+  }
+  const offset = selection.startLine - selection.rangeStartLine;
+  if (offset < 0) {
+    return false;
+  }
+  const previewLines = selection.preview.replace(/\\r\\n/g, "\\n").replace(/\\r/g, "\\n").split("\\n");
+  const contextLines = [
+    offset > 0 ? previewLines[offset - 1] : undefined,
+    previewLines[offset + selectedLineCount],
+  ].filter((line): line is string => Boolean(line?.trim()));
+  return contextLines.some((line) => suggestedLines.includes(line));
+}
+
+function hasUnchangedSelectionEdge(originalLines: string[], suggestedLines: string[]): boolean {
+  const firstLineUnchanged = originalLines[0] === suggestedLines[0];
+  const lastLineUnchanged = originalLines.at(-1) === suggestedLines.at(-1);
+  if (originalLines.length === suggestedLines.length || originalLines.length === 1) {
+    return firstLineUnchanged || lastLineUnchanged;
+  }
+  return firstLineUnchanged && lastLineUnchanged;
+}
+
+function suggestionsTable(suggestions: FixSuggestion[]): string {
+  if (suggestions.length === 0) {
+    return [
+      "| Category | Title |",
+      "| --- | --- |",
+      "| - | No exact suggested fixes found. |",
+    ].join("\\n");
+  }
+  return [
+    "| Category | Title |",
+    "| --- | --- |",
+    ...suggestions.map((suggestion) => {
+      const category = suggestion.category
+        .replaceAll("-", " ")
+        .replace(/^./, (char) => char.toUpperCase());
+      const title = suggestion.title.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      return \`| \${category} | \${title} |\`;
+    }),
+  ].join("\\n");
+}
+`
+};
+//#endregion
 //#region src/config/recipes/interactive-ask.ts
 const interactiveAskRecipe = {
 	id: "interactive-ask",
@@ -1483,7 +1754,7 @@ const prBriefingRecipe = {
 	title: "PR Briefing",
 	description: "PR-Agent describe-style overview, risk summary, and walkthrough.",
 	sourceTools: ["PR-Agent /describe", "CodeRabbit PR summaries"],
-	configTs: `import { definePipr } from "@usepipr/sdk";
+	configTs: `import { definePipr, z } from "@usepipr/sdk";
 
 export default definePipr((pipr) => {
   const model = pipr.model({
@@ -1495,33 +1766,178 @@ export default definePipr((pipr) => {
 
   pipr.config({ publication: { maxInlineComments: 0 } });
 
-  pipr.review({
-    id: "pr-briefing",
+  const briefingSchema = z.strictObject({
+    summary: z.string(),
+    prType: z.enum(["feature", "bugfix", "refactor", "docs", "tests", "dependency", "infra", "mixed"]),
+    riskLevel: z.enum(["low", "medium", "high"]),
+    riskSummary: z.string(),
+    changeMap: z.array(z.strictObject({
+      area: z.string(),
+      files: z.array(z.string()).max(6),
+      change: z.string(),
+    })).max(8),
+    reviewerFocus: z.array(z.string()).max(6),
+    notableFiles: z.array(z.strictObject({
+      path: z.string(),
+      reason: z.string(),
+    })).max(8),
+    walkthrough: z.array(z.string()).max(8),
+    diagramMermaid: z.string().optional(),
+  });
+
+  type Briefing = z.infer<typeof briefingSchema>;
+
+  const briefingOutput = pipr.schema({
+    id: "briefing/pr-reviewer",
+    schema: briefingSchema,
+  });
+
+  const briefing = pipr.agent({
+    name: "pr-briefing",
     model,
     instructions: \`
       Produce a maintainer briefing instead of a defect hunt. Summarize what changed,
-      classify the PR type, explain review risk, and include a concise file walkthrough.
-      Return no inline findings unless there is a concrete blocker.
+      classify the PR type, explain review risk, list notable files, and include
+      a concise reviewer walkthrough. Use reviewerFocus for what humans should
+      inspect first. Use diagramMermaid only when a small flowchart clarifies
+      multi-step control flow, data flow, or package boundaries; omit it for
+      straightforward changes. Do not report inline findings.
     \`,
-    comment: (result, context) => [
-      "## PR Briefing",
-      "",
-      \`**Change:** \${context.change.title}\`,
-      "",
-      result.summary.body,
-      "",
-      "\`\`\`mermaid",
-      "flowchart LR",
-      "  A[Changed files] --> B[Review focus]",
-      "  B --> C[Merge decision]",
-      "\`\`\`",
-    ].join("\\n"),
-    entrypoints: {
-      changeRequest: ["opened", "updated", "reopened", "ready"],
-      command: { pattern: "@pipr describe", permission: "read" },
+    output: briefingOutput,
+    tools: pipr.tools.readOnly,
+    retry: { invalidOutput: 1, transientFailure: 1 },
+    timeout: "7m",
+    prompt: () => "Prepare a maintainer briefing for this pull request.",
+  });
+
+  const task = pipr.task({
+    name: "pr-briefing",
+    async run(ctx) {
+      const manifest = await ctx.change.diffManifest({ compressed: true });
+      const result = await ctx.pi.run(briefing, { manifest, change: ctx.change });
+      const reviewerFocus =
+        result.reviewerFocus.length === 0
+          ? "No special reviewer focus called out."
+          : result.reviewerFocus.map((item) => \`- \${item}\`).join("\\n");
+      const walkthrough =
+        result.walkthrough.length === 0
+          ? "No walkthrough notes."
+          : result.walkthrough.map((item) => \`- \${item}\`).join("\\n");
+      await ctx.comment([
+        overviewTable(result, ctx.change.title),
+        "",
+        "## Summary",
+        "",
+        result.summary,
+        "",
+        "## Change Map",
+        "",
+        changeMapTable(result.changeMap),
+        "",
+        "## Reviewer Focus",
+        "",
+        reviewerFocus,
+        "",
+        "## Notable Files",
+        "",
+        notableFilesTable(result.notableFiles),
+        "",
+        "## Walkthrough",
+        "",
+        walkthrough,
+        "",
+        diagramBlock(result.diagramMermaid),
+      ].filter(Boolean).join("\\n"));
     },
   });
+
+  pipr.on.changeRequest({ actions: ["opened", "updated", "reopened", "ready"], task });
+  pipr.command({
+    pattern: "@pipr describe",
+    permission: "read",
+    description: "Generate a reviewer briefing for this pull request.",
+    task,
+  });
 });
+
+function overviewTable(briefing: Briefing, title: string): string {
+  const titleCell = title.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+  const prType = briefing.prType.replaceAll("-", " ").replace(/^./, (char) => char.toUpperCase());
+  const riskLevel = briefing.riskLevel
+    .replaceAll("-", " ")
+    .replace(/^./, (char) => char.toUpperCase());
+  const riskSummary = briefing.riskSummary.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+  return [
+    "| Change | Type | Risk | Risk summary |",
+    "| --- | --- | --- | --- |",
+    \`| \${titleCell} | \${prType} | \${riskLevel} | \${riskSummary} |\`,
+  ].join("\\n");
+}
+
+function changeMapTable(changeMap: Briefing["changeMap"]): string {
+  if (changeMap.length === 0) {
+    return [
+      "| Area | Files | Change |",
+      "| --- | --- | --- |",
+      "| - | - | No changed areas summarized. |",
+    ].join("\\n");
+  }
+  return [
+    "| Area | Files | Change |",
+    "| --- | --- | --- |",
+    ...changeMap.map((item) => {
+      const area = item.area.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      const files = item.files.join("<br>").replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      const change = item.change.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      return \`| \${area} | \${files} | \${change} |\`;
+    }),
+  ].join("\\n");
+}
+
+function notableFilesTable(files: Briefing["notableFiles"]): string {
+  if (files.length === 0) {
+    return [
+      "| File | Why it matters |",
+      "| --- | --- |",
+      "| - | No notable files called out. |",
+    ].join("\\n");
+  }
+  return [
+    "| File | Why it matters |",
+    "| --- | --- |",
+    ...files.map((file) => {
+      const filePath = file.path.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      const reason = file.reason.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      return \`| \${filePath} | \${reason} |\`;
+    }),
+  ].join("\\n");
+}
+
+function diagramBlock(diagramMermaid: string | undefined): string {
+  const diagram = diagramMermaid?.trim();
+  if (!diagram) {
+    return "";
+  }
+  const fence = markdownFenceFor(diagram);
+  return [
+    "<details>",
+    "<summary>Flow diagram</summary>",
+    "",
+    \`\${fence}mermaid\`,
+    diagram,
+    fence,
+    "",
+    "</details>",
+  ].join("\\n");
+}
+
+function markdownFenceFor(value: string): string {
+  const longestBacktickRun = Math.max(
+    0,
+    ...[...value.matchAll(/\`+/g)].map((match) => match[0].length),
+  );
+  return "\`".repeat(Math.max(3, longestBacktickRun + 1));
+}
 `
 };
 //#endregion
@@ -1531,7 +1947,8 @@ const prHygieneRecipe = {
 	title: "PR Hygiene",
 	description: "Danger-style PR hygiene checks for tests, docs, lockfiles, and size.",
 	sourceTools: ["Danger JS"],
-	configTs: `import { definePipr } from "@usepipr/sdk";
+	configTs: `import { definePipr, z } from "@usepipr/sdk";
+import type { ReviewFinding } from "@usepipr/sdk";
 
 export default definePipr((pipr) => {
   const model = pipr.model({
@@ -1541,18 +1958,60 @@ export default definePipr((pipr) => {
     options: { thinking: "medium" },
   });
 
+  pipr.config({ publication: { maxInlineComments: 5 } });
+
+  const hygienePolicySchema = z.enum([
+    "tests",
+    "docs",
+    "lockfiles",
+    "generated-files",
+    "change-size",
+  ]);
+
+  const policyCheckSchema = z.strictObject({
+    policy: hygienePolicySchema,
+    status: z.enum(["pass", "attention", "not-applicable"]),
+    evidence: z.string(),
+  });
+
+  const hygieneFindingSchema = z.strictObject({
+    title: z.string(),
+    policy: hygienePolicySchema,
+    body: z.string(),
+    path: z.string(),
+    rangeId: z.string(),
+    side: z.enum(["RIGHT", "LEFT"]),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+    suggestedFix: z.string().optional(),
+  });
+
+  type PolicyCheck = z.infer<typeof policyCheckSchema>;
+  type HygieneFinding = z.infer<typeof hygieneFindingSchema>;
+
+  const hygieneOutput = pipr.schema({
+    id: "review/pr-hygiene",
+    schema: z.strictObject({
+      summary: z.string(),
+      checks: z.array(policyCheckSchema),
+      findings: z.array(hygieneFindingSchema),
+    }),
+  });
+
   const hygiene = pipr.agent({
     name: "pr-hygiene",
     model,
     instructions: \`
-      Review pull request hygiene. Check whether behavior changes include tests,
-      public API changes include docs or changelog notes, lockfile changes match manifests,
-      and the PR size is reasonable. Return concise actionable findings.
-    \`,
-    output: pipr.schemas.review,
-    prompt: (input: { manifest: unknown; changedFiles: unknown }) => pipr.prompt\`
-      \${pipr.section("Changed files", pipr.json(input.changedFiles, { maxCharacters: 20000 }))}
+      Review pull request hygiene, not code correctness. Evaluate tests, docs,
+      lockfiles, generated files, and change size. Return one policy check per
+      relevant policy. Return inline findings only for concrete hygiene gaps
+      that maintainers can act on in the changed lines.
     \`,
+    output: hygieneOutput,
+    tools: pipr.tools.readOnly,
+    retry: { invalidOutput: 1, transientFailure: 1 },
+    timeout: "6m",
+    prompt: () => "Check this pull request for repository hygiene and merge readiness.",
   });
 
   const task = pipr.task({
@@ -1563,10 +2022,34 @@ export default definePipr((pipr) => {
       ctx.log.info(\`Checking PR hygiene for \${changedFiles.length} changed file(s).\`);
       const manifest = await ctx.change.diffManifest({ compressed: true, maxPreviewLines: 80 });
       const result = await ctx.pi.run(hygiene, { manifest, changedFiles });
+      const inlineFindings: ReviewFinding[] = result.findings.map((finding) => {
+        const policy = finding.policy
+          .replaceAll("-", " ")
+          .replace(/^./, (char) => char.toUpperCase());
+        return {
+          body: \`**\${policy}:** \${finding.title}. \${finding.body}\`,
+          path: finding.path,
+          rangeId: finding.rangeId,
+          side: finding.side,
+          startLine: finding.startLine,
+          endLine: finding.endLine,
+          ...(finding.suggestedFix ? { suggestedFix: finding.suggestedFix } : {}),
+        };
+      });
       ctx.check.pass("PR hygiene review completed.");
       await ctx.comment({
-        main: result.summary.body,
-        inlineFindings: result.inlineFindings,
+        main: [
+          result.summary,
+          "",
+          "## Policy Checks",
+          "",
+          policyTable(result.checks),
+          "",
+          "## Selected Findings",
+          "",
+          findingsTable(result.findings),
+        ].join("\\n"),
+        inlineFindings,
       });
     },
   });
@@ -1574,6 +2057,51 @@ export default definePipr((pipr) => {
   pipr.on.changeRequest({ actions: ["opened", "updated", "reopened", "ready"], task });
   pipr.command({ pattern: "@pipr hygiene", permission: "write", task });
 });
+
+function policyTable(checks: PolicyCheck[]): string {
+  if (checks.length === 0) {
+    return [
+      "| Policy | Status | Evidence |",
+      "| --- | --- | --- |",
+      "| - | Not applicable | No policy checks were relevant. |",
+    ].join("\\n");
+  }
+  return [
+    "| Policy | Status | Evidence |",
+    "| --- | --- | --- |",
+    ...checks.map((check) => {
+      const policy = check.policy
+        .replaceAll("-", " ")
+        .replace(/^./, (char) => char.toUpperCase());
+      const status = check.status
+        .replaceAll("-", " ")
+        .replace(/^./, (char) => char.toUpperCase());
+      const evidence = check.evidence.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      return \`| \${policy} | \${status} | \${evidence} |\`;
+    }),
+  ].join("\\n");
+}
+
+function findingsTable(findings: HygieneFinding[]): string {
+  if (findings.length === 0) {
+    return [
+      "| Policy | Finding |",
+      "| --- | --- |",
+      "| - | No selected hygiene findings. |",
+    ].join("\\n");
+  }
+  return [
+    "| Policy | Finding |",
+    "| --- | --- |",
+    ...findings.map((finding) => {
+      const policy = finding.policy
+        .replaceAll("-", " ")
+        .replace(/^./, (char) => char.toUpperCase());
+      const title = finding.title.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      return \`| \${policy} | \${title} |\`;
+    }),
+  ].join("\\n");
+}
 `
 };
 //#endregion
@@ -1582,8 +2110,9 @@ const qualityGateRecipe = {
 	id: "quality-gate",
 	title: "Quality Gate",
 	description: "Required review check that fails on blocking correctness and test risks.",
-	sourceTools: ["SonarQube"],
-	configTs: `import { definePipr } from "@usepipr/sdk";
+	sourceTools: ["SonarQube", "Snyk"],
+	configTs: `import { definePipr, z } from "@usepipr/sdk";
+import type { CommentableRange, DiffManifest, ReviewFinding } from "@usepipr/sdk";
 
 export default definePipr((pipr) => {
   const model = pipr.model({
@@ -1616,21 +2145,467 @@ export default definePipr((pipr) => {
     },
   });
 
-  pipr.review({
-    id: "quality-gate",
+  const blockerSchema = z.strictObject({
+    title: z.string(),
+    category: z.enum(["correctness", "security", "reliability", "test-coverage"]),
+    impact: z.string(),
+    body: z.string(),
+    path: z.string(),
+    rangeId: z.string(),
+    side: z.enum(["RIGHT", "LEFT"]),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+    suggestedFix: z.string().optional(),
+  });
+
+  type QualityBlocker = z.infer<typeof blockerSchema>;
+
+  const qualityGateOutput = pipr.schema({
+    id: "review/quality-gate",
+    schema: z.strictObject({
+      summary: z.string(),
+      blockers: z.array(blockerSchema),
+    }),
+  });
+
+  const reviewer = pipr.agent({
+    name: "quality-gate",
     model,
     instructions: \`
-      Act as a merge quality gate. Report only blocking correctness,
-      security, reliability, or test coverage issues that must prevent merge.
-      If no blocking issue exists, state that no blocking issue exists.
+      Act as a merge quality gate. Report only blocking correctness, security,
+      reliability, or test coverage issues that must prevent merge. A blocker
+      must have a concrete changed-code range and an impact that maintainers can
+      verify. If no blocking issue exists, return an empty blockers array.
     \`,
+    output: qualityGateOutput,
+    tools: pipr.tools.readOnly,
+    retry: { invalidOutput: 1, transientFailure: 1 },
+    timeout: "7m",
+    prompt: () => "Run the required quality gate for this pull request.",
+  });
+
+  const task = pipr.task({
+    name: "quality-gate",
     check: { enabled: true, name: "quality gate", required: true },
-    comment: (result) => ({
-      main: \`## Quality Gate\\n\\n\${result.summary.body}\`,
-      inlineFindings: result.inlineFindings,
+    async run(ctx) {
+      const manifest = await ctx.change.diffManifest({ compressed: true });
+      const result = await ctx.pi.run(reviewer, { manifest });
+      const commentableBlockers = result.blockers.filter((blocker) =>
+        commentableRangeForFinding(blocker, manifest) !== undefined,
+      );
+      const droppedBlockerCount = result.blockers.length - commentableBlockers.length;
+      const inlineFindings: ReviewFinding[] = commentableBlockers.map((blocker) => {
+        const category = blocker.category
+          .replaceAll("-", " ")
+          .replace(/^./, (char) => char.toUpperCase());
+        return {
+          body: \`**\${category} blocker:** \${blocker.title}. \${blocker.body}\`,
+          path: blocker.path,
+          rangeId: blocker.rangeId,
+          side: blocker.side,
+          startLine: blocker.startLine,
+          endLine: blocker.endLine,
+          ...(blocker.suggestedFix ? { suggestedFix: blocker.suggestedFix } : {}),
+        };
+      });
+
+      if (commentableBlockers.length > 0) {
+        const issueNoun = commentableBlockers.length === 1 ? "issue" : "issues";
+        ctx.check.fail(\`\${commentableBlockers.length} blocking quality \${issueNoun} found.\`);
+      } else {
+        ctx.check.pass("No blocking quality issues found.");
+      }
+
+      await ctx.comment({
+        main: [
+          statusTable(commentableBlockers),
+          "",
+          droppedBlockersNote(droppedBlockerCount),
+          "",
+          result.summary,
+          "",
+          "## Blocking Findings",
+          "",
+          blockersTable(commentableBlockers),
+          "",
+          "## Category Breakdown",
+          "",
+          categoryBreakdownTable(commentableBlockers),
+        ].join("\\n"),
+        inlineFindings,
+      });
+    },
+  });
+
+  pipr.on.changeRequest({ actions: ["opened", "updated", "reopened", "ready"], task });
+  pipr.command({ pattern: "@pipr quality", permission: "write", task });
+});
+
+type FindingAnchor = Pick<ReviewFinding, "path" | "rangeId" | "side" | "startLine" | "endLine">;
+
+function commentableRangeForFinding(
+  finding: FindingAnchor,
+  manifest: DiffManifest,
+): CommentableRange | undefined {
+  for (const file of manifest.files) {
+    const range = file.commentableRanges.find((candidate) => candidate.id === finding.rangeId);
+    if (!range) {
+      continue;
+    }
+    return finding.rangeId === range.id &&
+      finding.path === range.path &&
+      finding.side === range.side &&
+      finding.startLine <= finding.endLine &&
+      finding.startLine >= range.startLine &&
+      finding.endLine <= range.endLine
+      ? range
+      : undefined;
+  }
+  return undefined;
+}
+
+function statusTable(blockers: QualityBlocker[]): string {
+  return [
+    "| Status | Blocking findings | Categories |",
+    "| --- | ---: | --- |",
+    \`| \${blockers.length === 0 ? "Pass" : "Fail"} | \${blockers.length} | \${categorySummary(
+      blockers,
+    )} |\`,
+  ].join("\\n");
+}
+
+function blockersTable(blockers: QualityBlocker[]): string {
+  if (blockers.length === 0) {
+    return [
+      "| Category | Title | Impact |",
+      "| --- | --- | --- |",
+      "| - | No blocking findings. | - |",
+    ].join("\\n");
+  }
+  return [
+    "| Category | Title | Impact |",
+    "| --- | --- | --- |",
+    ...blockers.map((blocker) => {
+      const category = blocker.category
+        .replaceAll("-", " ")
+        .replace(/^./, (char) => char.toUpperCase());
+      const title = blocker.title.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      const impact = blocker.impact.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      return \`| \${category} | \${title} | \${impact} |\`;
+    }),
+  ].join("\\n");
+}
+
+function droppedBlockersNote(count: number): string {
+  if (count === 0) {
+    return "";
+  }
+  const blockerNoun = count === 1 ? "blocker" : "blockers";
+  const verb = count === 1 ? "was" : "were";
+  const pronoun = count === 1 ? "it does" : "they do";
+  return [
+    "<sub>",
+    count,
+    " model-reported ",
+    blockerNoun,
+    " ",
+    verb,
+    " ignored because ",
+    pronoun,
+    " not match a commentable diff range.",
+    "</sub>",
+  ].join("");
+}
+
+function categoryBreakdownTable(blockers: QualityBlocker[]): string {
+  const counts = categoryCounts(blockers);
+  if (counts.length === 0) {
+    return [
+      "| Category | Count |",
+      "| --- | ---: |",
+      "| - | 0 |",
+    ].join("\\n");
+  }
+  return [
+    "| Category | Count |",
+    "| --- | ---: |",
+    ...counts.map(([category, count]) => {
+      const categoryLabel = category
+        .replaceAll("-", " ")
+        .replace(/^./, (char) => char.toUpperCase());
+      return \`| \${categoryLabel} | \${count} |\`;
+    }),
+  ].join("\\n");
+}
+
+function categorySummary(blockers: QualityBlocker[]): string {
+  const counts = categoryCounts(blockers);
+  if (counts.length === 0) {
+    return "None";
+  }
+  return counts
+    .map(([category, count]) => {
+      const categoryLabel = category
+        .replaceAll("-", " ")
+        .replace(/^./, (char) => char.toUpperCase());
+      return \`\${categoryLabel} (\${count})\`;
+    })
+    .join(", ");
+}
+
+function categoryCounts(blockers: QualityBlocker[]): Array<[string, number]> {
+  const counts = new Map<string, number>();
+  for (const blocker of blockers) {
+    counts.set(blocker.category, (counts.get(blocker.category) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+}
+
+`
+};
+//#endregion
+//#region src/config/recipes/rich-review.ts
+const structuredReviewRecipe = {
+	id: "rich-review",
+	title: "Structured Review",
+	description: "General pull request review with severity and category metadata.",
+	sourceTools: [
+		"CodeRabbit",
+		"Qodo Merge",
+		"Greptile"
+	],
+	configTs: `import { definePipr, z } from "@usepipr/sdk";
+import type { ReviewFinding } from "@usepipr/sdk";
+
+type CategorizedFinding = {
+  title: string;
+  severity: "critical" | "high" | "medium" | "low" | "nit";
+  category:
+    | "correctness"
+    | "security"
+    | "reliability"
+    | "performance"
+    | "test-coverage"
+    | "maintainability"
+    | "documentation";
+  rationale: string;
+  body: string;
+  path: string;
+  rangeId: string;
+  side: "RIGHT" | "LEFT";
+  startLine: number;
+  endLine: number;
+  suggestedFix?: string;
+};
+
+type ReviewSummary = {
+  headline: string;
+  changeSummary: string[];
+  riskLevel: "low" | "medium" | "high";
+  riskSummary: string;
+  reviewerFocus: string[];
+};
+
+const categorizedFindingSchema = z.strictObject({
+  title: z.string(),
+  severity: z.enum(["critical", "high", "medium", "low", "nit"]),
+  category: z.enum([
+    "correctness",
+    "security",
+    "reliability",
+    "performance",
+    "test-coverage",
+    "maintainability",
+    "documentation",
+  ]),
+  rationale: z.string(),
+  body: z.string(),
+  path: z.string(),
+  rangeId: z.string(),
+  side: z.enum(["RIGHT", "LEFT"]),
+  startLine: z.number().int().positive(),
+  endLine: z.number().int().positive(),
+  suggestedFix: z.string().optional(),
+});
+
+const reviewSummarySchema = z.strictObject({
+  headline: z.string(),
+  changeSummary: z.array(z.string()).min(1).max(4),
+  riskLevel: z.enum(["low", "medium", "high"]),
+  riskSummary: z.string(),
+  reviewerFocus: z.array(z.string()).max(4),
+});
+
+export default definePipr((pipr) => {
+  const model = pipr.model({
+    provider: "deepseek",
+    model: "deepseek-v4-pro",
+    apiKey: pipr.secret({ name: "DEEPSEEK_API_KEY" }),
+    options: { thinking: "high" },
+  });
+
+  pipr.config({ publication: { maxInlineComments: 8 } });
+
+  const reviewOutput = pipr.schema({
+    id: "review/categorized-findings",
+    schema: z.strictObject({
+      summary: reviewSummarySchema,
+      findings: z.array(categorizedFindingSchema),
     }),
   });
+
+  const reviewer = pipr.agent({
+    name: "reviewer",
+    model,
+    instructions: \`
+      Review the pull request diff for correctness, security, reliability,
+      performance, test coverage, maintainability, and documentation risks.
+      Return only actionable findings that target valid diff ranges. Assign
+      severity by merge impact: critical and high for merge-blocking defects,
+      medium for important follow-up, low for minor actionable improvements,
+      and nit only for tiny but concrete issues. Include suggestedFix only when
+      there is an exact replacement for the selected range.
+
+      Make summary maintainer-facing and scannable: one concrete headline, one
+      to four behavior-focused change bullets, a risk level with rationale, and
+      reviewer focus only for useful human follow-up. Put actionable defects in
+      findings, not only in summary.
+    \`,
+    output: reviewOutput,
+    tools: pipr.tools.readOnly,
+    retry: { invalidOutput: 1, transientFailure: 1 },
+    timeout: "10m",
+    prompt: () => "Review this change with severity and category metadata.",
+  });
+
+  const task = pipr.task({
+    name: "review",
+    async run(ctx) {
+      const manifest = await ctx.change.diffManifest({ compressed: true });
+      const result = await ctx.pi.run(reviewer, { manifest });
+      const inlineFindings: ReviewFinding[] = result.findings.map((finding) => {
+        const severity = finding.severity.charAt(0).toUpperCase() + finding.severity.slice(1);
+        const category = finding.category.replaceAll("-", " ");
+        return {
+          body: \`**\${severity} \${category}:** \${finding.title}. \${finding.body}\`,
+          path: finding.path,
+          rangeId: finding.rangeId,
+          side: finding.side,
+          startLine: finding.startLine,
+          endLine: finding.endLine,
+          ...(finding.suggestedFix ? { suggestedFix: finding.suggestedFix } : {}),
+        };
+      });
+      await ctx.comment({
+        main: [
+          "## Summary",
+          "",
+          \`**\${result.summary.headline}**\`,
+          "",
+          summaryTable(result.summary, result.findings.length),
+          "",
+          "## What Changed",
+          "",
+          bulletList(result.summary.changeSummary, "No changed behavior summarized."),
+          "",
+          "## Reviewer Focus",
+          "",
+          bulletList(result.summary.reviewerFocus, "No special reviewer focus."),
+          "",
+          "## Findings",
+          "",
+          findingsTable(result.findings),
+          ...(result.findings.length > 0 ? ["", findingRationalesBlock(result.findings)] : []),
+        ].join("\\n"),
+        inlineFindings,
+      });
+    },
+  });
+
+  pipr.on.changeRequest({ actions: ["opened", "updated", "reopened", "ready"], task });
+  pipr.command({ pattern: "@pipr review", permission: "write", task });
 });
+
+function summaryTable(summary: ReviewSummary, findingCount: number): string {
+  return [
+    "| Outcome | Risk | Risk summary |",
+    "| --- | --- | --- |",
+    \`| \${findingOutcome(findingCount)} | \${labelValue(summary.riskLevel)} | \${tableCell(
+      summary.riskSummary,
+    )} |\`,
+  ].join("\\n");
+}
+
+function findingOutcome(findingCount: number): string {
+  if (findingCount === 0) {
+    return "No findings";
+  }
+  return findingCount === 1 ? "1 finding" : \`\${findingCount} findings\`;
+}
+
+function findingsTable(findings: CategorizedFinding[]): string {
+  if (findings.length === 0) {
+    return [
+      "| Severity | Category | Title |",
+      "| --- | --- | --- |",
+      "| - | - | No findings. |",
+    ].join("\\n");
+  }
+  return [
+    "| Severity | Category | Title |",
+    "| --- | --- | --- |",
+    ...findings.map((finding) => {
+      const severity = finding.severity.charAt(0).toUpperCase() + finding.severity.slice(1);
+      const category = finding.category.replaceAll("-", " ").replaceAll("|", "\\\\|");
+      const title = finding.title.replaceAll("\\n", " ").replaceAll("|", "\\\\|");
+      return \`| \${severity} | \${category} | \${title} |\`;
+    }),
+  ].join("\\n");
+}
+
+function findingRationalesBlock(findings: CategorizedFinding[]): string {
+  if (findings.length === 0) {
+    return "";
+  }
+  return [
+    "<details>",
+    "<summary>Finding rationales</summary>",
+    "",
+    findings
+      .map((finding, index) =>
+        [
+          \`### \${index + 1}. \${finding.title}\`,
+          "",
+          \`**Severity:** \${labelValue(finding.severity)}\`,
+          \`**Category:** \${labelValue(finding.category)}\`,
+          "",
+          finding.rationale,
+        ].join("\\n"),
+      )
+      .join("\\n\\n"),
+    "",
+    "</details>",
+  ].join("\\n");
+}
+
+function bulletList(items: string[], emptyText: string): string {
+  if (items.length === 0) {
+    return emptyText;
+  }
+  return items.map((item) => \`- \${lineText(item)}\`).join("\\n");
+}
+
+function labelValue(value: string): string {
+  return value.replaceAll("-", " ").replace(/^./, (char) => char.toUpperCase());
+}
+
+function lineText(value: string): string {
+  return value.replaceAll("\\n", " ").trim();
+}
+
+function tableCell(value: string): string {
+  return lineText(value).replaceAll("|", "\\\\|");
+}
 `
 };
 //#endregion
@@ -1647,15 +2622,25 @@ const securitySastRecipe = {
 	configTs: `import { definePipr } from "@usepipr/sdk";
 import type { ReviewFinding } from "@usepipr/sdk";
 
+type SecuritySummary = {
+  headline: string;
+  riskLevel: "low" | "medium" | "high";
+  riskSummary: string;
+  reviewerFocus: string[];
+};
+
+type SecurityRisk = {
+  title: string;
+  category: "auth" | "injection" | "secret" | "crypto" | "data-exposure" | "other";
+  severity: "low" | "medium" | "high" | "critical";
+  rationale: string;
+  finding?: ReviewFinding;
+};
+
 type SecurityReview = {
-  summary: string;
-  risks: Array<{
-    title: string;
-    category: "auth" | "injection" | "secret" | "crypto" | "data-exposure" | "other";
-    severity: "low" | "medium" | "high" | "critical";
-    rationale: string;
-    finding?: ReviewFinding;
-  }>;
+  summary: SecuritySummary;
+  risks: SecurityRisk[];
+  diagramMermaid?: string;
 };
 
 export default definePipr((pipr) => {
@@ -1673,7 +2658,20 @@ export default definePipr((pipr) => {
       additionalProperties: false,
       required: ["summary", "risks"],
       properties: {
-        summary: { type: "string" },
+        summary: {
+          type: "object",
+          additionalProperties: false,
+          required: ["headline", "riskLevel", "riskSummary", "reviewerFocus"],
+          properties: {
+            headline: { type: "string" },
+            riskLevel: { type: "string", enum: ["low", "medium", "high"] },
+            riskSummary: { type: "string" },
+            reviewerFocus: {
+              type: "array",
+              items: { type: "string" },
+            },
+          },
+        },
         risks: {
           type: "array",
           items: {
@@ -1705,6 +2703,7 @@ export default definePipr((pipr) => {
             },
           },
         },
+        diagramMermaid: { type: "string" },
       },
     },
   });
@@ -1716,6 +2715,11 @@ export default definePipr((pipr) => {
       Review for exploitable security issues only. Focus on auth bypasses,
       injection, unsafe deserialization, secret exposure, cryptography misuse,
       authorization gaps, and data exposure. Do not report hypothetical style issues.
+      Make summary maintainer-facing and scannable with a concrete headline,
+      risk level, risk rationale, and only useful security follow-up. Set
+      diagramMermaid only when a high or critical risk has a concrete source-to-sink
+      path and a small Mermaid flowchart clarifies it. Do not include Markdown
+      fences in diagramMermaid.
     \`,
     output: securityOutput,
     tools: pipr.tools.readOnly,
@@ -1731,14 +2735,40 @@ export default definePipr((pipr) => {
     async run(ctx) {
       const manifest = await ctx.change.diffManifest({ compressed: true });
       const result = await ctx.pi.run(security, { manifest });
-      const inlineFindings = result.risks.flatMap((risk) => (risk.finding ? [risk.finding] : []));
-      if (result.risks.some((risk) => risk.severity === "critical" || risk.severity === "high")) {
+      const inlineFindings: ReviewFinding[] = result.risks.flatMap((risk) =>
+        risk.finding ? [risk.finding] : [],
+      );
+      const hasHighOrCriticalRisk = result.risks.some(isHighOrCriticalRisk);
+      const hasConcreteHighOrCriticalRisk = result.risks.some(
+        (risk) => isHighOrCriticalRisk(risk) && risk.finding,
+      );
+      if (hasHighOrCriticalRisk) {
         ctx.check.fail("High or critical security risk found.");
       } else {
         ctx.check.pass("No high or critical security risks found.");
       }
       await ctx.comment({
-        main: \`## Security SAST\\n\\n\${result.summary}\`,
+        main: [
+          "## Summary",
+          "",
+          \`**\${result.summary.headline}**\`,
+          "",
+          securityStatusTable(result.summary, result.risks),
+          "",
+          result.summary.riskSummary,
+          "",
+          "## Reviewer Focus",
+          "",
+          bulletList(result.summary.reviewerFocus, "No special security follow-up."),
+          "",
+          "## Security Risks",
+          "",
+          securityRisksTable(result.risks),
+          ...(result.risks.length > 0 ? ["", riskRationalesBlock(result.risks)] : []),
+          ...(hasConcreteHighOrCriticalRisk && result.diagramMermaid?.trim()
+            ? ["", attackPathDiagramBlock(result.diagramMermaid, hasConcreteHighOrCriticalRisk)]
+            : []),
+        ].join("\\n"),
         inlineFindings,
       });
     },
@@ -1747,6 +2777,122 @@ export default definePipr((pipr) => {
   pipr.on.changeRequest({ actions: ["opened", "updated", "reopened", "ready"], task });
   pipr.command({ pattern: "@pipr security", permission: "write", task });
 });
+
+function securityStatusTable(summary: SecuritySummary, risks: SecurityRisk[]): string {
+  return [
+    "| Status | Summary risk | Max severity | Risks |",
+    "| --- | --- | --- | ---: |",
+    \`| \${risks.some(isHighOrCriticalRisk) ? "Fail" : "Pass"} | \${labelValue(
+      summary.riskLevel,
+    )} | \${maxSeverity(risks)} | \${risks.length} |\`,
+  ].join("\\n");
+}
+
+function securityRisksTable(risks: SecurityRisk[]): string {
+  if (risks.length === 0) {
+    return [
+      "| Severity | Category | Title |",
+      "| --- | --- | --- |",
+      "| - | - | No security risks found. |",
+    ].join("\\n");
+  }
+  return [
+    "| Severity | Category | Title |",
+    "| --- | --- | --- |",
+    ...risks.map(
+      (risk) =>
+        \`| \${labelValue(risk.severity)} | \${tableCell(risk.category)} | \${tableCell(risk.title)} |\`,
+    ),
+  ].join("\\n");
+}
+
+function riskRationalesBlock(risks: SecurityRisk[]): string {
+  if (risks.length === 0) {
+    return "";
+  }
+  return [
+    "<details>",
+    "<summary>Risk rationales</summary>",
+    "",
+    risks
+      .map((risk, index) =>
+        [
+          \`### \${index + 1}. \${risk.title}\`,
+          "",
+          \`**Severity:** \${labelValue(risk.severity)}\`,
+          \`**Category:** \${labelValue(risk.category)}\`,
+          "",
+          risk.rationale,
+        ].join("\\n"),
+      )
+      .join("\\n\\n"),
+    "",
+    "</details>",
+  ].join("\\n");
+}
+
+function attackPathDiagramBlock(
+  diagramMermaid: string | undefined,
+  hasConcreteHighOrCriticalRisk: boolean,
+): string {
+  const diagram = diagramMermaid?.trim();
+  if (!diagram || !hasConcreteHighOrCriticalRisk) {
+    return "";
+  }
+  const fence = markdownFenceFor(diagram);
+  return [
+    "<details>",
+    "<summary>Attack path diagram</summary>",
+    "",
+    \`\${fence}mermaid\`,
+    diagram,
+    fence,
+    "",
+    "</details>",
+  ].join("\\n");
+}
+
+function maxSeverity(risks: SecurityRisk[]): string {
+  const order: SecurityRisk["severity"][] = ["low", "medium", "high", "critical"];
+  const severity = risks.reduce<SecurityRisk["severity"] | undefined>((current, risk) => {
+    if (!current || order.indexOf(risk.severity) > order.indexOf(current)) {
+      return risk.severity;
+    }
+    return current;
+  }, undefined);
+  return severity ? labelValue(severity) : "None";
+}
+
+function isHighOrCriticalRisk(risk: SecurityRisk): boolean {
+  return risk.severity === "high" || risk.severity === "critical";
+}
+
+function bulletList(items: string[], emptyText: string): string {
+  if (items.length === 0) {
+    return emptyText;
+  }
+  return items.map((item) => \`- \${lineText(item)}\`).join("\\n");
+}
+
+function labelValue(value: string): string {
+  return value.replaceAll("-", " ").replace(/^./, (char) => char.toUpperCase());
+}
+
+function lineText(value: string): string {
+  return value.replaceAll("\\n", " ").trim();
+}
+
+function tableCell(value: string): string {
+  return lineText(value).replaceAll("|", "\\\\|");
+}
+
+function markdownFenceFor(value: string): string {
+  const longestBacktickRun = Math.max(
+    0,
+    ...[...value.matchAll(/\`+/g)].map((match) => match[0].length),
+  );
+  return "\`".repeat(Math.max(3, longestBacktickRun + 1));
+}
 `
 };
 //#endregion
@@ -1754,6 +2900,8 @@ export default definePipr((pipr) => {
 const supportedOfficialInitRecipes = [
 	"default-review",
 	"bug-hunter",
+	"rich-review",
+	"fix-suggestions",
 	"security-sast",
 	"quality-gate",
 	"diff-diagnostics",
@@ -1769,6 +2917,8 @@ const supportedOfficialInitRecipes = [
 const officialInitRecipeRegistry = {
 	"default-review": defaultReviewRecipe,
 	"bug-hunter": bugHunterRecipe,
+	"rich-review": structuredReviewRecipe,
+	"fix-suggestions": fixSuggestionsRecipe,
 	"security-sast": securitySastRecipe,
 	"quality-gate": qualityGateRecipe,
 	"diff-diagnostics": diffDiagnosticsRecipe,
@@ -1804,8 +2954,8 @@ function isOfficialInitRecipeId(recipe) {
 //#endregion
 //#region src/config/init.ts
 const supportedOfficialInitAdapters = ["github"];
-const defaultWorkflowActionRef = "somus/pipr@v0.3.1";
-const defaultSdkVersion = "0.3.1";
+const defaultWorkflowActionRef = "somus/pipr@v0.3.3";
+const defaultSdkVersion = "0.3.3";
 const defaultTypesBunVersion = "1.3.14";
 function resolveOfficialInitAdapters(adapters) {
 	if (adapters === void 0) return [...supportedOfficialInitAdapters];
@@ -3890,7 +5040,19 @@ function buildRepairPrompt(options) {
 }
 //#endregion
 //#region package.json
-var version = "0.3.1";
+var version = "0.3.3";
+//#endregion
+//#region src/review/comment-branding.ts
+const piprLogoUrl = "https://pipr.run/images/pipr/pipr-mark.svg";
+const piprRepositoryUrl = "https://github.com/somus/pipr";
+const mainCommentTitle = `# <img src="${piprLogoUrl}" width="22" height="22" alt=""> Pipr Review`;
+const mainCommentTitles = new Set([
+	"# pipr Review",
+	"# Pipr Review",
+	mainCommentTitle
+]);
+const escapedRepositoryUrl = piprRepositoryUrl.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const mainCommentAttributionPattern = new RegExp(`^<sub>Review generated by \\[Pipr\\]\\(${escapedRepositoryUrl}\\) for commit \`[^\`]+\`\\.</sub>$`);
 //#endregion
 //#region src/review/inline-publication-policy.ts
 const maxSuggestedFixSelectedLines = 12;
@@ -4280,7 +5442,8 @@ function buildPublicationPlan(options) {
 		mainComment: renderMainComment({
 			event: options.event,
 			reviewState,
-			main: options.main
+			main: options.main,
+			reviewedHeadSha: metadata.reviewedHeadSha
 		}),
 		mainMarker: mainCommentMarker,
 		changeNumber: options.event.change.number,
@@ -4364,26 +5527,39 @@ function renderMainComment(options) {
 			reviewState: options.reviewState
 		}),
 		"",
-		"# Pipr Review",
+		mainCommentTitle,
 		"",
 		redactPotentialSecrets(options.main),
+		"",
+		`<sub>Review generated by [Pipr](${piprRepositoryUrl}) for commit \`${options.reviewedHeadSha.slice(0, 7)}\`.</sub>`,
 		""
 	].join("\n");
 }
 function renderInlineBody(finding, findingId, reviewedHeadSha) {
+	const findingBody = startsWithStructuredMarkdown(finding.body) ? finding.body : [
+		"**Issue**",
+		"",
+		finding.body
+	].join("\n");
 	return [
 		renderInlineFindingMarker(findingId, reviewedHeadSha),
-		finding.body,
-		finding.suggestedFix ? `\n${renderSuggestedChange(finding.suggestedFix)}` : ""
+		findingBody,
+		finding.suggestedFix ? [
+			"**Suggested change**",
+			"",
+			renderSuggestedChange(finding.suggestedFix)
+		].join("\n") : ""
 	].filter(Boolean).join("\n");
 }
+function startsWithStructuredMarkdown(value) {
+	const body = value.trimStart();
+	return /^#{1,6}\s/.test(body) || /^>/.test(body) || /^(\d+[.)]|[-*+])\s/.test(body) || /^\|/.test(body) || /^(```|~~~)/.test(body) || /^<\s*[a-z][\w:-]*(\s|>|\/>)/i.test(body) || /^\*\*[^*\n]+\*\*/.test(body);
+}
 function renderSuggestedChange(suggestedFix) {
-	const fence = "`".repeat(Math.max(3, longestBacktickRun(suggestedFix) + 1));
+	const longestBacktickRun = Math.max(0, ...[...suggestedFix.matchAll(/`+/g)].map((match) => match[0].length));
+	const fence = "`".repeat(Math.max(3, longestBacktickRun + 1));
 	return `${fence}suggestion\n${suggestedFix}${suggestedFix.endsWith("\n") ? "" : "\n"}${fence}`;
 }
-function longestBacktickRun(value) {
-	return Math.max(0, ...[...value.matchAll(/`+/g)].map((match) => match[0].length));
-}
 //#endregion
 //#region src/review/comment-publishing.ts
 function buildCommentPublishingPlan(options) {
@@ -4771,9 +5947,9 @@ function priorReviewForTask(priorMainComment, priorReviewState) {
 	};
 }
 function visibleMainComment(body) {
-	const lines = body.split("\n").filter((line) => !line.startsWith("<!-- pipr:main-comment "));
+	const lines = body.split("\n").filter((line) => !line.startsWith("<!-- pipr:main-comment ") && !mainCommentAttributionPattern.test(line));
 	while (lines[0] === "") lines.shift();
-	if (lines[0] === "# pipr Review" || lines[0] === "# Pipr Review") lines.shift();
+	if (lines[0] && mainCommentTitles.has(lines[0])) lines.shift();
 	while (lines[0] === "") lines.shift();
 	return lines.join("\n").trim();
 }
@@ -7376,4 +8552,4 @@ async function runActionCommandWithDependencies(options) {
 //#endregion
 export { runInspectCommand as a, PublicationError as c, listOfficialInitRecipes as d, supportedOfficialInitRecipes as f, piThinkingLevels as g, piRequiredCliFlags as h, runInitCommand as i, isPublishableSuggestedFixSelection as l, piReadOnlyToolNames as m, runActionCommandWithDependencies as n, runLocalReviewCommand as o, piBuiltinToolNames as p, runDryRunCommand as r, runValidateCommand as s, runActionCommand as t, supportedOfficialInitAdapters as u };
 
-//# sourceMappingURL=commands-BNxl37V6.mjs.map
+//# sourceMappingURL=commands-C1sVsbEj.mjs.map