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

package/package.json

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

@@ -69,27 +69,30 @@ ignored); a version outside the supported set degrades to a §5.5 sticky notice.
 | `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. |
+| `v0.6.0` | superseded | 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. |
+| `v0.9.0` | **current** | Adds a REQUIRED `likelihood` (0..1) to every finding and systemic problem (issue #163): the probability the triggering input/state actually occurs — distinct from `confidence` (whether the defect is real) — folded into the convergence score as a second multiplier. **Breaking**: a pre-0.9 document lacks `likelihood` and no longer validates, so a stale sticky degrades to a sentinel-only seed (one cold re-review) rather than seeding. The draft axis skips `0.7`/`0.8`: those are the surface-signal axis's versions (below), so the draft jumps past them to keep the two version spaces distinct — a draft must never be mistaken for a legacy surfaced blob (issue #156). |
 
-### Surfaced findings document
+### Surface channel (stop signal)
 
-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:
+The commenter embeds the agent's **complete** findings document verbatim in review comments
+(`<!-- code-review:findings-json -->`) — no surfaced copy, no added fields (issue #156). The
+deterministic stop signal an iterating author-agent needs rides its own compact
+`<!-- code-review:signal -->` marker beside the blob: 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 the signal (it cannot know the score — the weights and threshold are
+commenter-side), so the findings schema above describes the whole embedded document; the signal
+marker declares its own surface version:
 
 | 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). |
+| `v0.7.0` | superseded | The pre-#156 surface axis: the commenter embedded a **surfaced** copy of the findings document carrying `convergence` + `round` inside it (issue #141). A sticky written by a `0.7.0` release still seeds — `stripSurfaceFields` peels the surfaced copy back to the agent's draft. |
+| `v0.8.0` | **current** | The version the compact `code-review:signal` marker declares (and the version a legacy `0.8.0` surfaced blob declared). `0.8.0` added the agent-facing `scope_metastasis` entry (issue #150): per-code consecutive-round recurrence counts plus a decision prompt. Post-#156 that entry is embedded in no document — the re-review seed re-derives it from the rounds marker and delivers it to the next-round agent. The flat draft schema (now `v0.9.0`) accepts an optional `scope_metastasis` property so a seed-echoing draft validates — an in-place additive change, deliberately NOT a draft version bump: a draft sharing a `0.7.0`/`0.8.0` number would collide with the surface axis's version gate, so the draft axis skips past them to `0.9.0` (issue #163); the axes must stay distinct so `stripSurfaceFields`/`parseSurfaceSignal` can tell a legacy surfaced blob 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.
+The surface axis is independent of the draft-version registry: `v0.8.0` is the signal marker's
+contract, while the agent-written document above is now `v0.9.0`. `stripSurfaceFields` and
+`parseSurfaceSignal` are version-gated on the surface axis, so a future draft bump can never be
+mistaken for a legacy surfaced blob — and no fresh document is ever surfaced.
 
 ### Price-map schema
 

package/schema/findings.schema.json

@@ -27,7 +27,7 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["title", "description", "severity", "reasoning", "confidence"],
+        "required": ["title", "description", "severity", "reasoning", "confidence", "likelihood"],
         "properties": {
           "title": {
             "type": "string",
@@ -52,6 +52,12 @@
             "maximum": 1,
             "description": "0..1 confidence in the systemic problem itself. Mirrors the finding field of the same name."
           },
+          "likelihood": {
+            "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."
+          },
           "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."
@@ -81,7 +87,7 @@
     "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.",
+      "description": "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 re-derives it from the carried round history and delivers it in the prior review context of a re-review. When it is present, 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": {
@@ -131,7 +137,8 @@
           "title",
           "description",
           "reasoning",
-          "confidence"
+          "confidence",
+          "likelihood"
         ],
         "properties": {
           "path": {
@@ -186,6 +193,12 @@
             "maximum": 1,
             "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."
           },
+          "likelihood": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "0..1 probability the triggering input or state actually occurs in practice — from a normal user in routine use, OR from an adversary who chooses it when the finding is a security issue. Distinct from confidence (which rates whether the defect is real): a footgun that fires only on hostile-to-oneself input is high-confidence yet low-likelihood. Anchors: 0.9 = any normal input, or any input an attacker can choose (e.g. an injectable query parameter); 0.5 = a plausible-but-uncommon configuration; 0.1 = a genuinely obscure state no one seeks; 0.02 = requires deliberately hostile-to-oneself input (e.g. naming a struct field \"__slots__\"). Name the triggering input, then rate how routinely it occurs."
+          },
           "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."