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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jphutchins/code-review",
-  "version": "0.1.0-alpha.43",
+  "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,7 +69,8 @@ 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). |
 
 ### Surface channel (stop signal)
 
@@ -86,10 +87,10 @@ marker declares its own surface version:
 | Version | Status | Notes |
 |---|---|---|
 | `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 (still `v0.6.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 `0.7.0` draft would collide with the surface axis's version gate (the axes must stay distinct so `stripSurfaceFields`/`parseSurfaceSignal` can tell a legacy surfaced blob from a 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 surface axis is independent of the draft-version registry: `v0.8.0` is the signal marker's
-contract, while the agent-written document above remains at `v0.6.0`. `stripSurfaceFields` and
+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.
 

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."
@@ -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."