@jphutchins/code-review 0.1.0-alpha.4 → 0.1.0-alpha.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jphutchins/code-review",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.41",
   "description": "Deterministic commenter for agentic PR review — gather, render, inline, post, adapt, extract, cost, validate, print-schema",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,7 @@
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.9.4",
     "tsup": "^8.3.5",
+    "tsx": "^4.23.0",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.62.1",
     "vitest": "^3.0.4"

package/schema/VERSIONING.md

@@ -65,7 +65,31 @@ ignored); a version outside the supported set degrades to a §5.5 sticky notice.
 | Version | Status | Notes |
 |---|---|---|
 | `v0.1.0` | superseded | Initial schema. Matches the proven camas reference implementation. |
-| `v0.2.0` | **current** | Adds required `schema_version`; optional `code`/`code_url` finding fields; normative `suggestion` `""`/`null` semantics; abstract vendor-neutral envelope (see SPEC §6.1). |
+| `v0.2.0` | superseded | Adds required `schema_version`; optional `code`/`code_url` finding fields; normative `suggestion` `""`/`null` semantics; abstract vendor-neutral envelope (see SPEC §6.1). |
+| `v0.3.0` | superseded | Adds optional `reasoning` finding field. |
+| `v0.4.0` | superseded | Breaking: renames finding `body` → `description`; makes `reasoning` and `confidence` **required**; adds optional `recommendation` (prose fix); removes the free-text `suggestion` field (a `patch`, now `string \| null`, is the sole mechanical fix, projected into a suggestion by the commenter). |
+| `v0.5.0` | superseded | Widens the `verdict` enum with a pipeline-reserved `error` value: a run that produced no verdict about the diff (operational failure or security refusal) now carries `verdict: "error"` with `findings: []`, so its machine-readable blob is no longer byte-identical to a clean pass. Backwards-compatible (a `0.4` document is a valid `0.5` document); the CLI keeps resolving `0.4` via an identity upcast, so a sticky embedded by a `0.4` CLI still seeds a re-review. |
+| `v0.6.0` | **current** | Adds optional `systemic_problems` — an array of cross-cutting observations that tie findings together and are hard to express with a line range, each item with required `title`/`description`/`severity`/`reasoning`/`confidence` and optional `code`/`code_url`/`finding_codes`/`paths` (no line anchors). Refocuses `summary` on justifying the overall verdict rather than restating findings. Backwards-compatible (a `0.5` document is a valid `0.6` document); the CLI keeps resolving `0.4`/`0.5` via identity upcasts, so stickies embedded by earlier CLIs still seed a re-review. |
+
+### Surfaced findings document
+
+The commenter does not embed the agent's raw findings document in review comments — it embeds a
+**surfaced** copy (`<!-- code-review:findings-json -->`): the same fields, stamped with a surface
+version and the pipeline-computed `convergence` (`{score, threshold, converged}` — a literal
+boolean, so a decoding agent cannot re-derive the weights) and `round` (the count of completed
+full-review rounds) of the last completed full-review round. The agent never writes these fields
+(it cannot know the score — the weights and threshold are commenter-side), so the findings schema
+above describes only the agent-written document; the surfaced document has its own version axis:
+
+| Version | Status | Notes |
+|---|---|---|
+| `v0.7.0` | superseded | The surfaced document carries `convergence` + `round` — the deterministic stop signal an iterating author-agent decodes instead of the prose (issue #141). Both are omitted until at least one full-review round has completed, and both survive the in-progress banner (carried forward verbatim with the marker). `stripSurfaceFields` drops them when a surfaced blob feeds back into the agent channel (the re-review seed), restoring the draft version. This surface axis is deliberately **distinct** from the draft axis (now `v0.6.0` after issue #134) so a surfaced doc is never mistaken for an agent-written draft. |
+| `v0.8.0` | **current** | Adds the agent-facing `scope_metastasis` entry (issue #150): per-code consecutive-round recurrence counts plus a decision prompt, computed from the same rounds history the prose metastasis note renders. Unlike `convergence`/`round` it is NOT stripped by `stripSurfaceFields` — the re-review seed must deliver the recurrence data to the next-round agent, so the agent can respond to the scope decision instead of letting the end state emerge piecemeal. To tolerate a seed-echoing draft, the flat draft schema (still `v0.6.0`) additionally accepts an optional `scope_metastasis` property — an in-place additive change, deliberately NOT a draft version bump: a `0.7.0` draft would collide with the surfaced axis's version gate (the axes must stay distinct so `stripSurfaceFields`/`parseSurfaceSignal` can tell a surfaced doc from a draft). |
+
+The surfaced axis is independent of the draft-version registry: `v0.8.0` is the surface shape's
+marker contract, while the agent-written document above remains at `v0.6.0`. `stripSurfaceFields`
+and `parseSurfaceSignal` are version-gated on the surface axis, so a future draft bump can never be
+mistaken for a surfaced document.
 
 ### Price-map schema
 

package/schema/findings.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/JPHutchins/code-review/main/schema/findings.schema.json",
   "title": "Code Review — findings",
-  "description": "Structured output of an agentic PR review. The review agent emits this object (e.g. via a coding-agent CLI's structured-output mode, such as Claude Code's `--json-schema`, whose result lands in `.structured_output`); a deterministic commenter renders it into a sticky summary comment and inline PR review comments. Agent- and provider-agnostic: any model driven by a compatible CLI adapter may produce it. Kept free of $ref/$defs so the same file works for both JSON-Schema validators and CLI structured-output enforcement.",
+  "description": "Structured output of an agentic PR code review. The review agent emits this object (e.g. via a coding-agent CLI's structured-output mode, such as Claude Code's `--json-schema`, whose result lands in `.structured_output`, or a file).",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_version", "summary", "verdict", "findings"],
@@ -10,24 +10,129 @@
     "schema_version": {
       "type": "string",
       "pattern": "^(0|[1-9]\\d*)\\.(\\d+)\\.(\\d+)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
-      "description": "Semver version of this findings schema the object conforms to (e.g. \"0.1.0\"). Lets a commenter detect a version mismatch rather than silently dropping fields."
+      "description": "Semver version of this findings schema the object conforms to (e.g. \"0.1.0\")."
     },
     "summary": {
       "type": "string",
-      "description": "Markdown walkthrough of the change and the overall assessment; rendered as the body of the sticky summary comment."
+      "description": "1-4 sentence markdown justification of the overall verdict — the shape of the review and why the verdict follows from it. Do not restate individual findings (those live in `findings`) or cross-cutting observations (those live in `systemic_problems`); the summary explains the verdict, the arrays carry the evidence."
     },
     "verdict": {
       "type": "string",
-      "enum": ["approve", "comment", "changes"],
-      "description": "Overall stance. Advisory only: a conforming commenter posts the GitHub review as COMMENT and never REQUEST_CHANGES, surfacing this value as a badge."
+      "enum": ["approve", "comment", "changes", "error"],
+      "description": "Overall stance. The review agent emits one of `approve`/`comment`/`changes`. `error` is reserved for the pipeline: it marks a run that produced no verdict about the diff (an operational failure, a security refusal, or an empty diff with nothing to review — always with `findings: []`), so a consumer switching on `verdict` gets a case it does not recognise rather than a false clean pass."
+    },
+    "systemic_problems": {
+      "type": "array",
+      "description": "Zero or more cross-cutting observations that tie several findings together or describe a pattern spanning the change, and are hard to express with a single line range. Omit the field when there are none; the summary must not restate them.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["title", "description", "severity", "reasoning", "confidence"],
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "One-line summary of the systemic problem."
+          },
+          "description": {
+            "type": "string",
+            "description": "1-3 sentence markdown explanation of the pattern and why it matters — how it ties the related findings together. Details belong in the individual findings' `reasoning`."
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "major", "minor", "nit"],
+            "description": "Overall severity of the systemic problem — the severity of the pattern itself, not of any single finding. It does not count toward the findings severity histogram."
+          },
+          "reasoning": {
+            "type": "string",
+            "description": "Rationale/evidence for why the systemic problem holds, so a human or downstream agent can judge its soundness — distinct from `description`, which explains the pattern to the reader. Mirrors the finding field of the same name."
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "0..1 confidence in the systemic problem itself. Mirrors the finding field of the same name."
+          },
+          "code": {
+            "type": "string",
+            "description": "Stable rule identifier (e.g. \"repeated-null-check\") for rule-based filtering, suppression, and cross-run dedup — mirrors the finding field of the same name."
+          },
+          "code_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL documenting the rule named by code."
+          },
+          "finding_codes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The `code` values of the findings this systemic problem ties together, when those findings carry codes."
+          },
+          "paths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Repo-relative file paths the systemic problem spans."
+          }
+        }
+      }
+    },
+    "scope_metastasis": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Pipeline-stamped advisory (issue #150): the mechanisms whose findings recurred in consecutive prior full-review rounds — per-code consecutive-round counts plus a decision prompt. The review agent does NOT write this field: the commenter computes it from the carried round history and stamps it into the surfaced document. When it is present in the prior review context of a re-review, respond to the decision prompt — state in your summary whether you are committing to the expanding scope (planning the remaining facets of the recurring mechanism(s) as one unit) or narrowing the scope — so the decision is made explicitly rather than left to emerge piecemeal.",
+      "required": ["decision_prompt", "recurring"],
+      "properties": {
+        "decision_prompt": {
+          "type": "string",
+          "description": "The scope decision to make in the summary of the next review — a decision, not a directive."
+        },
+        "recurring": {
+          "type": "array",
+          "description": "The mechanisms flagged: one entry per code whose findings recurred in `consecutive_rounds` or more consecutive completed full-review rounds.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["code", "consecutive_rounds", "start_round"],
+            "properties": {
+              "code": {
+                "type": "string",
+                "description": "The finding code of the recurring mechanism."
+              },
+              "consecutive_rounds": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991,
+                "description": "How many consecutive completed full-review rounds (ending at the last completed round) carried a finding with this code. Same-head CI retries are collapsed by the streak detector, so this is the de-duplicated streak, not the raw span: it may be less than `round - start_round + 1` when the history contains retries."
+              },
+              "start_round": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991,
+                "description": "The 1-indexed round where the consecutive streak began."
+              }
+            }
+          }
+        }
+      }
     },
     "findings": {
       "type": "array",
-      "description": "Zero or more specific findings. Each becomes one inline review comment when its line is inside the diff; otherwise it is demoted into the summary.",
+      "description": "Zero or more specific findings.",
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["path", "start_line", "end_line", "severity", "title", "body"],
+        "required": [
+          "path",
+          "start_line",
+          "end_line",
+          "severity",
+          "title",
+          "description",
+          "reasoning",
+          "confidence"
+        ],
         "properties": {
           "path": {
             "type": "string",
@@ -47,7 +152,7 @@
             "type": "string",
             "enum": ["RIGHT", "LEFT"],
             "default": "RIGHT",
-            "description": "RIGHT for added/changed lines, LEFT for removed lines; matches the GitHub pulls reviews API."
+            "description": "As in a unified-diff view: RIGHT for added/changed lines, LEFT for removed lines."
           },
           "severity": {
             "type": "string",
@@ -67,19 +172,27 @@
             "type": "string",
             "description": "One-line summary of the finding."
           },
-          "body": {
+          "description": {
             "type": "string",
-            "description": "Markdown explanation; rendered as the inline comment body."
+            "description": "1-3 sentence markdown explanation of what is wrong. Details belong in `reasoning`."
           },
-          "suggestion": {
-            "type": ["string", "null"],
-            "description": "null = no mechanical fix (render no suggestion block); \"\" (empty string) = delete start_line..end_line (render an empty suggestion block); non-empty = exact replacement text for start_line..end_line (render a GitHub suggestion block). A suggestion spanning more than GitHub's single-block line limit is demoted to the summary."
+          "recommendation": {
+            "type": "string",
+            "description": "1-2 sentence markdown prose describing what to do about the finding — distinct from `patch`, which is a machine-applicable unified diff. Use this when the fix is best explained rather than mechanically applied, or to accompany a `patch` with rationale."
           },
           "confidence": {
             "type": "number",
             "minimum": 0,
             "maximum": 1,
-            "description": "Optional 0..1 confidence; a commenter MAY suppress findings below a configurable threshold to control noise, but MUST NOT suppress a critical-severity finding on confidence alone."
+            "description": "0..1 confidence; a commenter MAY suppress findings below a configurable threshold to control noise, but MUST NOT suppress a critical-severity finding on confidence alone."
+          },
+          "reasoning": {
+            "type": "string",
+            "description": "Rationale/evidence for why the finding holds, so a human or downstream agent can judge its soundness — distinct from `description`, which explains the finding to the reader."
+          },
+          "patch": {
+            "type": "string",
+            "description": "Optional single-hunk unified diff of one mechanical fix to this file, expressed against its current (post-change) content — e.g. the `git diff` of just that edit after you apply it. It MUST be exactly one hunk and one contiguous change, and its context and removed lines MUST match the file verbatim so it applies cleanly. Omit this field when there is no clean mechanical fix — never invent one; put prose guidance in `recommendation` instead."
           }
         }
       }

package/schema/v0.2/findings.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/JPHutchins/code-review/schema-v0.2.0/schema/findings.schema.json",
+  "title": "Code Review — findings",
+  "description": "Structured output of an agentic PR review. The review agent emits this object (e.g. via a coding-agent CLI's structured-output mode, such as Claude Code's `--json-schema`, whose result lands in `.structured_output`); a deterministic commenter renders it into a sticky summary comment and inline PR review comments. Agent- and provider-agnostic: any model driven by a compatible CLI adapter may produce it. Kept free of $ref/$defs so the same file works for both JSON-Schema validators and CLI structured-output enforcement.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "summary", "verdict", "findings"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(\\d+)\\.(\\d+)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
+      "description": "Semver version of this findings schema the object conforms to (e.g. \"0.1.0\"). Lets a commenter detect a version mismatch rather than silently dropping fields."
+    },
+    "summary": {
+      "type": "string",
+      "description": "Markdown walkthrough of the change and the overall assessment; rendered as the body of the sticky summary comment."
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["approve", "comment", "changes"],
+      "description": "Overall stance. Advisory only: a conforming commenter posts the GitHub review as COMMENT and never REQUEST_CHANGES, surfacing this value as a badge."
+    },
+    "findings": {
+      "type": "array",
+      "description": "Zero or more specific findings. Each becomes one inline review comment when its line is inside the diff; otherwise it is demoted into the summary.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "start_line", "end_line", "severity", "title", "body"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Repo-relative file path the finding anchors to."
+          },
+          "start_line": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-indexed first line of the anchored range (post-change state when side is RIGHT)."
+          },
+          "end_line": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-indexed last line of the range; MUST be >= start_line. A suggestion replaces exactly start_line..end_line."
+          },
+          "side": {
+            "type": "string",
+            "enum": ["RIGHT", "LEFT"],
+            "default": "RIGHT",
+            "description": "RIGHT for added/changed lines, LEFT for removed lines; matches the GitHub pulls reviews API."
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "major", "minor", "nit"],
+            "description": "Used for grouping and for folding nits into a collapsed section."
+          },
+          "code": {
+            "type": "string",
+            "description": "Stable rule identifier (e.g. \"null-check-missing\") for rule-based filtering, suppression, and cross-run dedup."
+          },
+          "code_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL documenting the rule named by code."
+          },
+          "title": {
+            "type": "string",
+            "description": "One-line summary of the finding."
+          },
+          "body": {
+            "type": "string",
+            "description": "Markdown explanation; rendered as the inline comment body."
+          },
+          "suggestion": {
+            "type": ["string", "null"],
+            "description": "null = no mechanical fix (render no suggestion block); \"\" (empty string) = delete start_line..end_line (render an empty suggestion block); non-empty = exact replacement text for start_line..end_line (render a GitHub suggestion block). A suggestion spanning more than GitHub's single-block line limit is demoted to the summary."
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "Optional 0..1 confidence; a commenter MAY suppress findings below a configurable threshold to control noise, but MUST NOT suppress a critical-severity finding on confidence alone."
+          }
+        }
+      }
+    }
+  }
+}

package/templates/comment.eta

@@ -1,43 +1,122 @@
 <!-- code-review -->
 <!-- reviewed-sha: <%= it.reviewedSha %> -->
+<% if (!it.incomplete && it.route) { -%>
+<!-- reviewed-route: <%= it.route %> -->
+<% } -%>
+<% if (!it.incomplete) { -%>
+<!-- review-complete -->
+<% } -%>
+<% if (it.findingsPointer) { -%>
+<%~ it.findingsPointer %>
+<% } -%>
+<% if (it.roundsMarker) { -%>
+<%~ it.roundsMarker %>
+<% } -%>
 
 ### <%= it.verdictBadge(it.findings.verdict) %>
 
-<% const meta = [] %><% if (it.route) { meta.push('**Route:** ' + it.route) } %><% if (it.effort) { meta.push('**effort:** ' + it.effort) } %><% if (it.usageAvailable) { meta.push('**turns:** ' + it.envelope.turns); meta.push('**wall:** ' + it.formatDuration(it.envelope.duration_ms)) } else { meta.push('_usage unavailable_') } %><%~ meta.join(' · ') %>
+<% const meta = [] %><% if (it.postedAt) { meta.push('**Reviewed** `' + it.reviewedSha.slice(0, 7) + '` at ' + it.postedAt) } %><% if (it.route) { meta.push('**route:** ' + it.route) } %><% if (it.effort) { meta.push('**effort:** ' + it.effort) } %><% if (it.hasUsage) { meta.push('**turns:** ' + it.envelope.turns); meta.push('**wall:** ' + it.formatDuration(it.envelope.duration_ms)); meta.push('**models:** ' + it.modelNames); meta.push('**cost:** ' + it.formatCost(it.costReport.totalCostUSD)) } else { meta.push('_usage unavailable_') } %><sub><%~ meta.join(' · ') %></sub>
+<% if (!it.incomplete) { -%>
+<% if (it.roundsSummary) { -%>
+<sub><%~ it.roundsSummary %></sub>
+<% } -%>
+<% if (it.convergenceSummary) { -%>
+<sub><%~ it.convergenceSummary %></sub>
+<% } -%>
+<% if (it.metastasisNote) { -%>
+<%~ it.metastasisNote %>
+<% } -%>
+<% if (it.answeredReRaiseNote) { -%>
+<%~ it.answeredReRaiseNote %>
+<% } -%>
+<% } -%>
 
 <%~ it.findings.summary %>
 
----
+<% if (!it.incomplete && it.systemic.length > 0) { -%>
 
-<% if (it.totalCount > 0) { %>
-#### 📊 Findings summary — <%= it.totalCount %> finding<%= it.totalCount === 1 ? '' : 's' %> on <%= it.fileCount %> file<%= it.fileCount === 1 ? '' : 's' %>
+### 🔗 Systemic problems
 
-<% if (it.visibleFindings.length > 0) { %>
-| Severity | File | Line | Summary |
-|---|---|---|---|
-<% it.visibleFindings.forEach(function(f) { %>
-| <%= it.severityEmoji(f.severity) %> <%= f.severity %> | `<%= f.path %>` | <%= f.start_line %><% if (f.start_line !== f.end_line) { %>–<%= f.end_line %><% } %> | <%= f.title %> |
-<% }) %>
+<% it.systemic.forEach(function(s) { -%>
+#### <%= it.severityEmoji(s.severity) %> (<%= s.severity %>) <%= s.title %> · confidence <%= it.formatConfidence(s.confidence) %>
+<% const meta = [] %><% if (s.paths && s.paths.length > 0) { meta.push('Affects: ' + s.paths.map(function(p) { return '`' + p + '`' }).join(', ')) } %><% if (s.finding_codes && s.finding_codes.length > 0) { meta.push('Ties together: ' + s.finding_codes.map(function(c) { return '`' + c + '`' }).join(', ')) } %><% if (meta.length > 0) { %>_<%~ meta.join(' · ') %>_<% } %>
 
-<% } %>
-<% if (it.nitFindings.length > 0) { %>
-<details>
-<summary>⚪ <%= it.nitFindings.length %> nit<%= it.nitFindings.length === 1 ? '' : 's' %> (folded)</summary>
+<%~ s.description %>
 
-| File | Line | Summary |
-|---|---|---|
-<% it.nitFindings.forEach(function(f) { %>
-| `<%= f.path %>` | <%= f.start_line %><% if (f.start_line !== f.end_line) { %>–<%= f.end_line %><% } %> | <%= f.title %> |
-<% }) %>
+> [!TIP]
+> <details><summary>Reasoning</summary>
+>
+<% s.reasoning.split("\n").forEach(function(rl) { -%>
+> <%= rl %>
+<% }) -%>
+>
+> </details>
+<% }) -%>
+<% } -%>
 
-</details>
+---
+
+<% const c = it.severityCounts %><% const findingsTotal = c.critical + c.major + c.minor + c.nit %>
+<% if (findingsTotal > 0) { %>
+<% const parts = [] %><% if (c.critical) { parts.push(it.severityEmoji('critical') + ' ' + c.critical) } %><% if (c.major) { parts.push(it.severityEmoji('major') + ' ' + c.major) } %><% if (c.minor) { parts.push(it.severityEmoji('minor') + ' ' + c.minor) } %><% if (c.nit) { parts.push(it.severityEmoji('nit') + ' ' + c.nit) } %>
+**Findings:** <%~ parts.join(' · ') %>
+<% } else if (!it.incomplete && it.systemic.length === 0 && !it.answeredReRaiseNote) { %>
+_No findings — clean review._
 <% } %>
 
-<% if (it.suggestionCount > 0) { %>
-<%= it.suggestionCount %> finding<%= it.suggestionCount === 1 ? '' : 's' %> included suggestions — see inline comments for details.
+<% if (it.inlineDisposition && it.inlineDisposition.kind === 'posted') { %>
+→ <%= it.inlineDisposition.count %> comment<%= it.inlineDisposition.count === 1 ? '' : 's' %> posted inline on `<%= it.inlineDisposition.sha.slice(0, 7) %>` — <% if (it.reviewUrl) { %>[see the review](<%~ it.reviewUrl %>)<% } else { %>see the review<% } %>.
+<% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'none-in-diff') { %>
+→ No inline comments — all findings are outside the diff (listed below).
+<% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'inline-unavailable') { %>
+→ ⚠️ Inline comments couldn't be posted for this review (GitHub rejected a comment's position) — every finding is listed below instead.
 <% } %>
-<% } else { %>
-_No findings — clean review._
+
+<% if (it.strays.length > 0) { %>
+### <% if (it.inlineDisposition && it.inlineDisposition.kind === 'no-envelope') { %>Findings (no inline review — result envelope lost)<% } else { %><%= (it.unanchoredCount && it.unanchoredCount > 0) ? 'Findings' : 'Findings outside the diff' %><% } %>
+<% if (it.inlineDisposition && it.inlineDisposition.kind === 'no-envelope') { %>
+_Every finding is listed below — the inline review could not be built because the result envelope was missing._
+<% } else if (it.unanchoredCount && it.unanchoredCount > 0) { %>
+_<%= it.unanchoredCount %> finding<%= it.unanchoredCount === 1 ? '' : 's' %> below couldn't be posted as inline comment<%= it.unanchoredCount === 1 ? '' : 's' %> (GitHub rejected the position)<% if (it.strays.length > it.unanchoredCount) { %>; the rest are outside the diff<% } %>._
+<% } %>
+
+<% it.strays.forEach(function(f) { -%>
+#### <%= it.severityEmoji(f.severity) %> (<%= f.severity %>) `<%= f.path %>:<%= f.start_line %><% if (f.start_line !== f.end_line) { %>–<%= f.end_line %><% } %>` — <%= f.title %> · confidence <%= it.formatConfidence(f.confidence) %>
+
+<%~ f.description %>
+<% if (f.code && it.sameRootNotes && Object.prototype.hasOwnProperty.call(it.sameRootNotes, f.code)) { -%>
+
+> ⚠️ <%~ it.sameRootNotes[f.code] %>
+<% } -%>
+<% if (f.answeredNote) { -%>
+
+> ↩️ <%~ f.answeredNote %>
+<% } -%>
+<% if (f.recommendation) { -%>
+
+**Recommended fix:** <%~ f.recommendation %>
+<% } -%>
+<% if (f.patchProjection.kind === "suggestion") { -%>
+
+```suggestion
+<%~ f.patchProjection.text %>
+```
+<% } else if (f.patchProjection.kind === "patch") { -%>
+
+```patch
+<%~ f.patchProjection.raw %>
+```
+<% } -%>
+
+> [!TIP]
+> <details><summary>Reasoning (<%= it.formatConfidence(f.confidence) %> confidence)</summary>
+>
+<% f.reasoning.split("\n").forEach(function(rl) { -%>
+> <%= rl %>
+<% }) -%>
+>
+> </details>
+<% }) %>
 <% } %>
 
 <% if (it.testReport) { %>
@@ -47,7 +126,7 @@ _No findings — clean review._
 <summary>📊 Test results — <%= it.testReport.passed %> passed, <%= it.testReport.failed %> failed</summary>
 
 <% if (it.testReport.failed > 0 && it.testReport.failures) { %>
-<% it.testReport.failures.forEach(function(f) { %>
+<% it.testReport.failures.forEach(function(f) { -%>
 - **<%= f.name %>**<% if (f.message) { %> — <%~ f.message %><% } %>
 <% }) %>
 <% } else { %>
@@ -59,24 +138,24 @@ All <%= it.testReport.total %> tests passed.
 
 ---
 
-<% if (it.usageAvailable && it.costReport.lines.length > 0) { %>
-<sub>
-
-| Model | Input | Output | Cache read | Cache write | Cost |
-|---|--:|--:|--:|--:|--:|
-<% it.costReport.lines.forEach(function(l) { %>
-| <%= l.model %> | <%= it.formatTokens(l.inputTokens) %> | <%= it.formatTokens(l.outputTokens) %> | <%= it.formatTokens(l.cacheReadTokens) %> | <%= it.formatTokens(l.cacheWriteTokens) %> | <%= it.formatCost(l.costUSD) %> |
-<% }) %>
-| **Total** | **<%= it.formatTokens(it.costReport.totalInputTokens) %>** | **<%= it.formatTokens(it.costReport.totalOutputTokens) %>** | **<%= it.formatTokens(it.costReport.totalCacheReadTokens) %>** | **<%= it.formatTokens(it.costReport.totalCacheWriteTokens) %>** | **<%= it.formatCost(it.costReport.totalCostUSD) %>** |
-
-</sub>
-<% } else if (it.usageAvailable) { %>
-<sub>No per-model usage was recorded for this run.</sub>
-<% } else { %>
+> [!WARNING]
+> **LLM Disclosure** — this review was produced by <%= it.modelNames || "unknown model" %>.
+>
+<% if (it.usageAvailable && it.costReport.lines.length > 0) { -%>
+> | Model | Input | Output | Cache read | Cache write | Cost |
+> |---|--:|--:|--:|--:|--:|
+<% it.costReport.lines.forEach(function(l) { -%>
+> | <%= l.model %> | <%= it.formatTokens(l.inputTokens) %> | <%= it.formatTokens(l.outputTokens) %> | <%= it.formatTokens(l.cacheReadTokens) %> | <%= it.formatTokens(l.cacheWriteTokens) %> | <%= it.formatCost(l.costUSD) %> |
+<% }) -%>
+> | **Total** | **<%= it.formatTokens(it.costReport.totalInputTokens) %>** | **<%= it.formatTokens(it.costReport.totalOutputTokens) %>** | **<%= it.formatTokens(it.costReport.totalCacheReadTokens) %>** | **<%= it.formatTokens(it.costReport.totalCacheWriteTokens) %>** | **<%= it.formatCost(it.costReport.totalCostUSD) %>** |
+<% } else if (it.usageAvailable) { -%>
+> No per-model usage was recorded for this run.
+<% } else { -%>
 > **Usage/cost unavailable** — the result envelope for this run was missing or malformed.
-<% } %>
-
-> [!NOTE]
-> **LLM Disclosure** — this review was produced by <%= it.modelNames || "unknown model" %> running
-> headless in an ephemeral, egress-locked CI runner with no write access to the repository. It is
-> advisory and does not block merge.
+<% } -%>
+<% if (it.usageAvailable && !it.pricesProvided) { -%>
+>
+> _Cost shown as **N/A** — [No `.github/prices.json`](https://github.com/JPHutchins/code-review/blob/main/schema/prices.example.json) price map to recompute from._
+<% } -%>
+>
+> _Generated by [code-review](https://github.com/JPHutchins/code-review)<% if (it.runUrl) { %> · [view the run & traces](<%~ it.runUrl %>)<% } %>._

package/templates/inline.eta

@@ -1,9 +1,40 @@
-<%~ it.body %>
+<% if (it.findingsPointer) { -%>
+<%~ it.findingsPointer %>
+<% } -%>
+<%= it.severityEmoji(it.severity) %> <%= it.severity.charAt(0).toUpperCase() + it.severity.slice(1) %>: **<%= it.title %>** · <%= it.formatConfidence(it.confidence) %> confidence
+
+<%~ it.description %>
+<% if (it.sameRootNote) { -%>
+
+> ⚠️ <%~ it.sameRootNote %>
+<% } -%>
+<% if (it.answeredNote) { -%>
+
+> ↩️ <%~ it.answeredNote %>
+<% } -%>
+<% if (it.recommendation) { -%>
+
+**Recommended fix:** <%~ it.recommendation %>
+<% } -%>
+<% if (it.patchProjection.kind === "suggestion") { -%>
 
-<% if (it.suggestion !== null && it.suggestion !== undefined) { %>
 ```suggestion
-<%~ it.suggestion %>
+<%~ it.patchProjection.text %>
+```
+<% } else if (it.patchProjection.kind === "patch") { -%>
+
+```patch
+<%~ it.patchProjection.raw %>
 ```
-<% } %>
+<% } -%>
 
-<sub>🤖 AI-generated — advisory only</sub>
+> [!TIP]
+> Generated by <%~ it.modelsText %>.
+> <details>
+> <summary>Reasoning</summary>
+>
+<% it.reasoning.split("\n").forEach(function(rl) { -%>
+> <%= rl %>
+<% }) -%>
+>
+> </details>