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

package/README.md

@@ -99,8 +99,51 @@ links to:
   downstream tool) SHOULD base64-decode and parse that marker rather than parse the comment's prose.
   Embedding in the comment (rather than only linking the artifact) keeps the pointer from expiring
   with artifact retention; when the encoded findings are too large to embed, the sticky falls back to
-  a `<!-- code-review:findings-json <url> -->` link marker instead — the shared serializer is
+  a `<!-- code-review:findings-json <url> -->` link marker instead (the linked `findings.json` is the
+  agent's draft and lacks the surfaced fields below) — the shared serializer is
   [`src/surface.ts`](src/surface.ts).
+
+  The embedded document is the **surfaced** findings document: the agent's findings
+  (`schema_version` 0.5.0 contract, which is what the review agent is held to and what
+  [`schema/findings.schema.json`](schema/findings.schema.json) validates) stamped with the
+  `0.7.0` surface version plus the pipeline-computed convergence state of the **last completed
+  full-review round**:
+
+  ```json
+  {
+    "schema_version": "0.7.0",
+    "verdict": "comment",
+    "summary": "...",
+    "convergence": { "score": 1, "threshold": 1, "converged": true },
+    "round": 2,
+    "findings": []
+  }
+  ```
+
+  `convergence` (`score` = critical·4 + major·2 + minor·1 + nit·0, `threshold` default 1, `converged`
+  = score ≤ threshold, as a literal boolean) and `round` (the count of completed full-review rounds)
+  are the deterministic **stop signal** for an iterating author-agent: `converged: true` means the
+  last completed round is at or below the convergence tolerance, so another iteration round is not
+  warranted. The agent never writes these fields — the commenter computes them from the review's own
+  severities at render time — and they are omitted until at least one full-review round has
+  completed. They survive the "review in progress" banner: the banner replaces only the sticky's
+  prose and carries the embedded marker forward verbatim. The 0.7.0 surfaced contract applies to the
+  **whole-document** marker only; each inline comment embeds a per-finding fragment
+  (`schema_version` + one finding) at the draft's own version, since the fragment carries no stop
+  signal.
+
+  Semantics on non-round posts: a mechanic (CI-fix) pass or an envelope-loss post embeds the
+  **last completed round's stored signal** (round + its own threshold — never re-derived, so an
+  operator changing `convergence_threshold` mid-PR cannot flip a stored `converged`) beside its own
+  findings, so the signal always describes the last completed full-review round, not the findings
+  that happen to sit beside it. A notice — a post whose verdict is `error` or whose run did not
+  complete (empty diff, corrupt output, did-not-complete) — embeds **no** signal in its own blob:
+  its document already says no review was produced this run, and a carried `converged` beside that
+  would read as a stop signal for a run that produced none; the last completed round's signal still
+  survives on the sticky in the compact `<!-- code-review:signal;base64 <base64> -->` marker, so
+  the next post reads it back. The same compact marker is emitted when the embedded payload is too
+  large and the whole-document marker falls back to the artifact link — an oversized review's stop
+  signal stays readable and can be carried forward.
 - **`code-review-transcript`** — the full Claude Code session transcripts for the triage and review
   phases. This is advisory/auditability only: it is never read by the comment job and never affects
   what gets posted.