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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jphutchins/code-review",
-  "version": "0.1.0-alpha.40",
+  "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",

package/schema/VERSIONING.md

@@ -83,9 +83,10 @@ above describes only the agent-written document; the surfaced document has its o
 
 | 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. |
+| `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.7.0` is the surface shape's
+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.

package/schema/findings.schema.json

@@ -78,6 +78,45 @@
         }
       }
     },
+    "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.",

package/templates/comment.eta

@@ -26,6 +26,9 @@
 <% if (it.metastasisNote) { -%>
 <%~ it.metastasisNote %>
 <% } -%>
+<% if (it.answeredReRaiseNote) { -%>
+<%~ it.answeredReRaiseNote %>
+<% } -%>
 <% } -%>
 
 <%~ it.findings.summary %>
@@ -57,7 +60,7 @@
 <% 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) { %>
+<% } else if (!it.incomplete && it.systemic.length === 0 && !it.answeredReRaiseNote) { %>
 _No findings — clean review._
 <% } %>
 
@@ -70,8 +73,10 @@ _No findings — clean review._
 <% } %>
 
 <% if (it.strays.length > 0) { %>
-### <%= (it.unanchoredCount && it.unanchoredCount > 0) ? 'Findings' : 'Findings outside the diff' %>
-<% if (it.unanchoredCount && it.unanchoredCount > 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<% } %>._
 <% } %>
 
@@ -83,6 +88,10 @@ _<%= it.unanchoredCount %> finding<%= it.unanchoredCount === 1 ? '' : 's' %> bel
 
 > ⚠️ <%~ it.sameRootNotes[f.code] %>
 <% } -%>
+<% if (f.answeredNote) { -%>
+
+> ↩️ <%~ f.answeredNote %>
+<% } -%>
 <% if (f.recommendation) { -%>
 
 **Recommended fix:** <%~ f.recommendation %>

package/templates/inline.eta

@@ -8,6 +8,10 @@
 
 > ⚠️ <%~ it.sameRootNote %>
 <% } -%>
+<% if (it.answeredNote) { -%>
+
+> ↩️ <%~ it.answeredNote %>
+<% } -%>
 <% if (it.recommendation) { -%>
 
 **Recommended fix:** <%~ it.recommendation %>