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

package/package.json

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

@@ -71,25 +71,27 @@ ignored); a version outside the supported set degrades to a §5.5 sticky notice.
 | `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:
+### Surface channel (stop signal)
+
+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 (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). |
 
-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 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 legacy surfaced blob — and no fresh document is ever surfaced.
 
 ### Price-map schema
 

package/schema/findings.schema.json

@@ -81,7 +81,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": {