@jphutchins/code-review 0.1.0-alpha.44 → 0.1.0-alpha.46

package/package.json

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

package/schema/findings.schema.json

@@ -56,7 +56,7 @@
             "type": "number",
             "minimum": 0,
             "maximum": 1,
-            "description": "0..1 probability the pattern's triggering condition actually occurs in practice. Mirrors the finding field of the same name."
+            "description": "Set to 1 for a systemic problem. A structural/cross-cutting observation has no single triggering input — it is definitionally always present — so the convergence score treats a systemic problem's likelihood as 1 and never discounts it. (Required for schema symmetry with a finding's likelihood; the written value is not read by the score.)"
           },
           "code": {
             "type": "string",
@@ -123,6 +123,55 @@
         }
       }
     },
+    "convergence": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Advisory (issue #174): the current round's convergence score, the threshold it is judged against, whether it converged, and the per-round trajectory. The review agent does NOT write this field — the pipeline computes the score deterministically from the findings (floor(severity) + headroom × confidence × likelihood, summed) and stamps it, so this JSON document is the sole source of the convergence data a decoding agent reads. `score` and `threshold` are both carried so the number is interpretable on its own (converged when score <= threshold); prior rounds are carried verbatim, so changing the threshold never rewrites a past round's score.",
+      "required": ["score", "threshold", "converged"],
+      "properties": {
+        "score": {
+          "type": "number",
+          "description": "This round's convergence score — the sum of every finding's and systemic problem's contribution, rounded to 2 decimals. Lower is closer to convergence."
+        },
+        "threshold": {
+          "type": "number",
+          "description": "The convergence tolerance in force for this round: the round is converged when score <= threshold."
+        },
+        "converged": {
+          "type": "boolean",
+          "description": "Whether this round converged (score <= threshold). Advisory only — never alters the verdict."
+        },
+        "rounds": {
+          "type": "array",
+          "description": "The convergence trajectory: one entry per completed full-review round, oldest first, this round's entry last. Each score is a historical snapshot carried verbatim.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["round"],
+            "properties": {
+              "round": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "The 1-indexed completed-round number this entry represents."
+              },
+              "score": {
+                "type": "number",
+                "description": "That round's convergence score, carried verbatim from when the round completed. Absent only for a round migrated from a pre-#174 sticky, which stored no score."
+              },
+              "codes": {
+                "type": "object",
+                "additionalProperties": { "type": "integer", "minimum": 0 },
+                "description": "That round's mechanism-frequency map: finding code -> number of findings carrying it. Feeds the same-mechanism and scope-metastasis recurrence signals."
+              },
+              "sha": {
+                "type": "string",
+                "description": "The reviewed head SHA (short form) for that round, so a same-head CI retry is recognised as the same iteration rather than new recurrence evidence."
+              }
+            }
+          }
+        }
+      }
+    },
     "findings": {
       "type": "array",
       "description": "Zero or more specific findings.",

package/templates/comment.eta

@@ -81,7 +81,7 @@ _<%= it.unanchoredCount %> finding<%= it.unanchoredCount === 1 ? '' : 's' %> bel
 <% } %>
 
 <% 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) %>
+#### <%= 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) %> · likelihood <%= it.formatConfidence(f.likelihood) %>
 
 <%~ f.description %>
 <% if (f.code && it.sameRootNotes && Object.prototype.hasOwnProperty.call(it.sameRootNotes, f.code)) { -%>
@@ -109,7 +109,7 @@ _<%= it.unanchoredCount %> finding<%= it.unanchoredCount === 1 ? '' : 's' %> bel
 <% } -%>
 
 > [!TIP]
-> <details><summary>Reasoning (<%= it.formatConfidence(f.confidence) %> confidence)</summary>
+> <details><summary>Reasoning (<%= it.formatConfidence(f.confidence) %> confidence · <%= it.formatConfidence(f.likelihood) %> likelihood)</summary>
 >
 <% f.reasoning.split("\n").forEach(function(rl) { -%>
 > <%= rl %>
@@ -119,6 +119,17 @@ _<%= it.unanchoredCount %> finding<%= it.unanchoredCount === 1 ? '' : 's' %> bel
 <% }) %>
 <% } %>
 
+<% if (it.suppressedNits && it.suppressedNits.length > 0) { %>
+> [!NOTE]
+> <details><summary>🔇 <%= it.suppressedNits.length %> nit<%= it.suppressedNits.length === 1 ? '' : 's' %> below the visibility floor (confidence × likelihood < <%= it.nitVisibilityFloor %>) — hidden</summary>
+>
+<% it.suppressedNits.forEach(function(n) { -%>
+> - `<%= n.path %>:<%= n.startLine %>` — <%= n.title %><% if (n.code) { %> (`<%= n.code %>`)<% } %> _(m = <%= n.m %>)_
+<% }) -%>
+>
+> </details>
+<% } %>
+
 <% if (it.testReport) { %>
 ---
 

package/templates/inline.eta

@@ -1,7 +1,7 @@
 <% 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.severityEmoji(it.severity) %> <%= it.severity.charAt(0).toUpperCase() + it.severity.slice(1) %>: **<%= it.title %>** · <%= it.formatConfidence(it.confidence) %> confidence · <%= it.formatConfidence(it.likelihood) %> likelihood
 
 <%~ it.description %>
 <% if (it.sameRootNote) { -%>