@jphutchins/code-review 0.1.0-alpha.39 → 0.1.0-alpha.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jphutchins/code-review",
-  "version": "0.1.0-alpha.39",
+  "version": "0.1.0-alpha.40",
   "description": "Deterministic commenter for agentic PR review — gather, render, inline, post, adapt, extract, cost, validate, print-schema",
   "type": "module",
   "license": "MIT",

package/schema/VERSIONING.md

@@ -68,7 +68,27 @@ ignored); a version outside the supported set degrades to a §5.5 sticky notice.
 | `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` | **current** | 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.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` | **current** | 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. |
+
+The surfaced axis is independent of the draft-version registry: `v0.7.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

@@ -14,13 +14,70 @@
     },
     "summary": {
       "type": "string",
-      "description": "1-4 sentence markdown walkthrough of the overall assessment."
+      "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", "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."
+          }
+        }
+      }
+    },
     "findings": {
       "type": "array",
       "description": "Zero or more specific findings.",

package/templates/comment.eta

@@ -1,5 +1,8 @@
 <!-- code-review -->
 <!-- reviewed-sha: <%= it.reviewedSha %> -->
+<% if (!it.incomplete && it.route) { -%>
+<!-- reviewed-route: <%= it.route %> -->
+<% } -%>
 <% if (!it.incomplete) { -%>
 <!-- review-complete -->
 <% } -%>
@@ -20,17 +23,41 @@
 <% if (it.convergenceSummary) { -%>
 <sub><%~ it.convergenceSummary %></sub>
 <% } -%>
+<% if (it.metastasisNote) { -%>
+<%~ it.metastasisNote %>
+<% } -%>
 <% } -%>
 
 <%~ it.findings.summary %>
 
+<% if (!it.incomplete && it.systemic.length > 0) { -%>
+
+### 🔗 Systemic problems
+
+<% 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(' · ') %>_<% } %>
+
+<%~ s.description %>
+
+> [!TIP]
+> <details><summary>Reasoning</summary>
+>
+<% s.reasoning.split("\n").forEach(function(rl) { -%>
+> <%= rl %>
+<% }) -%>
+>
+> </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) { %>
+<% } else if (!it.incomplete && it.systemic.length === 0) { %>
 _No findings — clean review._
 <% } %>
 
@@ -52,6 +79,10 @@ _<%= it.unanchoredCount %> finding<%= it.unanchoredCount === 1 ? '' : 's' %> bel
 #### <%= 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.recommendation) { -%>
 
 **Recommended fix:** <%~ f.recommendation %>

package/templates/inline.eta

@@ -4,6 +4,10 @@
 <%= 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.recommendation) { -%>
 
 **Recommended fix:** <%~ it.recommendation %>