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

package/README.md

@@ -100,61 +100,45 @@ 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 linked `findings.json` is the
-  agent's draft and lacks the surfaced fields below) — the shared serializer is
+  a `<!-- code-review:findings-json <url> -->` link marker instead. 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.6.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.8.0` surface version, the pipeline-computed convergence state of the **last completed
-  full-review round**, and the advisory `scope_metastasis` entry (issue #150):
+  The embedded document is the agent's **complete** findings document — the same `schema_version`
+  0.6.0 contract the review agent is held to and
+  [`schema/findings.schema.json`](schema/findings.schema.json) validates, and the same object the
+  comment is rendered from. It is embedded verbatim: no field is added or dropped, so the machine
+  channel can never carry less than, or drift from, the rendered prose.
 
   ```json
   {
-    "schema_version": "0.8.0",
+    "schema_version": "0.6.0",
     "verdict": "comment",
     "summary": "...",
-    "convergence": { "score": 1, "threshold": 1, "converged": true },
-    "round": 4,
-    "scope_metastasis": {
-      "decision_prompt": "Findings keep recurring in the same mechanism across consecutive rounds — each fix keeps enabling the next finding in that machinery. This is a decision, not a directive: state in your summary whether you are committing to the expanding scope (plan the remaining facets of the recurring mechanism(s) above as one unit) or narrowing the scope so the recurrence stops.",
-      "recurring": [
-        { "code": "mixin-field-guard-gap", "consecutive_rounds": 4, "start_round": 1 }
-      ]
-    },
     "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. `scope_metastasis` is the structured
-  counterpart of the sticky's "Scope metastasis" warning — per-code consecutive-round counts plus a
-  decision prompt — computed from the same rounds history and omitted when no mechanism recurred. It
-  is deliberately NOT stripped when a surfaced blob feeds the re-review seed: a decoding agent — and
-  the next-round reviewer — must see the recurrence data to answer the scope decision. The 0.8.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.
+  The deterministic **stop signal** for an iterating author-agent rides its own compact marker beside
+  the findings blob, `<!-- code-review:signal;base64 <base64> -->`, whose decoded payload is
+  `{ "schema_version": "0.8.0", "round": <n>, "convergence": { "score": <s>, "threshold": <t>, "converged": <bool> } }`.
+  `round` is the count of completed full-review rounds; `convergence.score` = critical·4 + major·2 +
+  minor·1 + nit·0, `threshold` defaults to 1, and `converged` = score ≤ threshold as a literal
+  boolean — `converged: true` means the last completed round is at or below the tolerance, so another
+  iteration round is not warranted. The commenter computes the signal from the review's own severities
+  (the agent never writes it); it appears once at least one full-review round has completed and is
+  carried verbatim afterward — a mechanic (CI-fix) pass or an envelope-loss notice re-emits the last
+  completed round's signal rather than re-deriving it, so an operator changing `convergence_threshold`
+  mid-PR cannot flip a stored `converged`, and a notice never fabricates a stop signal for a run that
+  produced no review. Both markers survive the "review in progress" banner, which replaces only the
+  sticky's prose and carries them forward verbatim.
+
+  Cross-round recurrence (the sticky's "Scope metastasis" warning) is carried structurally in the
+  `<!-- code-review:rounds;base64 <base64> -->` marker — per-round severity counts and mechanism
+  frequencies — from which the re-review seed re-derives the advisory `scope_metastasis` entry it
+  hands the next-round agent. It is deliberately NOT embedded in the findings blob: the blob is the
+  agent's own document, and a recurrence claim is round state the commenter owns. Each inline review
+  comment embeds only its own finding (a `schema_version` + one-finding fragment), so the sticky and
+  review-body markers remain the whole-document source of truth.
 - **`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.

package/dist/index.js

@@ -598,28 +598,15 @@ var convergenceSignal = (counts, threshold = DEFAULT_CONVERGENCE_THRESHOLD) => {
   return { score, threshold, converged: score <= threshold };
 };
 var signalForRound = (round, counts, threshold = DEFAULT_CONVERGENCE_THRESHOLD) => ({ round, convergence: convergenceSignal(counts, threshold) });
-var surfaceFindings = (findings, signal, scopeMetastasis = null) => {
-  const agentDoc = Object.fromEntries(
-    Object.entries(findings).filter(
-      ([key2]) => key2 !== "round" && key2 !== "convergence" && key2 !== "scope_metastasis"
-    )
-  );
-  return {
-    ...agentDoc,
-    schema_version: SURFACE_SCHEMA_VERSION,
-    ...signal === null ? {} : signal,
-    ...scopeMetastasis === null ? {} : { scope_metastasis: scopeMetastasis }
-  };
-};
 var signalMarker = (signal) => `<!-- code-review:signal;base64 ${Buffer.from(
   JSON.stringify({ schema_version: SURFACE_SCHEMA_VERSION, ...signal }),
   "utf-8"
 ).toString("base64")} -->`;
-var surfacedFindingsPointer = (findings, signal, jsonUrl, scopeMetastasis = null) => {
-  const marker = findingsPointer(surfaceFindings(findings, signal, scopeMetastasis), jsonUrl);
-  if (signal === null || marker.includes("<!-- code-review:findings-json;base64 ")) return marker;
-  return marker === "" ? signalMarker(signal) : `${marker}
-${signalMarker(signal)}`;
+var joinSignalMarker = (base, marker) => base === "" ? marker : `${base}
+${marker}`;
+var surfacedFindingsPointer = (findings, signal, jsonUrl) => {
+  const marker = findingsPointer(findings, jsonUrl);
+  return signal === null ? marker : joinSignalMarker(marker, signalMarker(signal));
 };
 var SIGNAL_RE = /<!-- code-review:signal;base64 ([A-Za-z0-9+/=]+) -->/;
 var parseSignalMarker = (body) => {
@@ -630,8 +617,7 @@ var parseSignalMarker = (body) => {
 var parseSurfaceSignal = (doc) => {
   if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return null;
   const o = doc;
-  const declared = o["schema_version"];
-  if (typeof declared !== "string" || !SURFACE_SCHEMA_VERSIONS.includes(declared)) return null;
+  if (!isSurfaceVersion(o["schema_version"])) return null;
   const round = o["round"];
   const convergence = o["convergence"];
   if (typeof round !== "number" || !Number.isSafeInteger(round) || round < 1) return null;
@@ -646,11 +632,11 @@ var parseSurfaceSignal = (doc) => {
   };
 };
 var SURFACE_SCHEMA_VERSIONS = ["0.7.0", SURFACE_SCHEMA_VERSION];
+var isSurfaceVersion = (version) => typeof version === "string" && SURFACE_SCHEMA_VERSIONS.includes(version);
 var stripSurfaceFields = (doc) => {
   if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return doc;
   const o = doc;
-  const declared = o["schema_version"];
-  if (typeof declared !== "string" || !SURFACE_SCHEMA_VERSIONS.includes(declared)) return doc;
+  if (!isSurfaceVersion(o["schema_version"])) return doc;
   const rest = Object.fromEntries(
     Object.entries(o).filter(([key2]) => key2 !== "convergence" && key2 !== "round")
   );
@@ -1059,7 +1045,6 @@ var render = (input) => {
   const isFullReviewRound = (input.convergenceRound ?? (isConvergenceRound(route, incomplete) && rounds.length > 0)) && isReviewVerdict(input.findings.verdict);
   const convergenceCounts = rounds[rounds.length - 1] ?? computeRoundCounts(input.findings);
   const advisoryAllowed = isFullReviewRound;
-  const scopeMetastasis = input.scopeMetastasis !== void 0 ? input.scopeMetastasis : advisoryAllowed ? computeScopeMetastasis(rounds) : null;
   return eta.renderString(input.template, {
     findings: input.findings,
     envelope: input.envelope,
@@ -1090,8 +1075,7 @@ var render = (input) => {
       // label does; post always supplies the marker, so this path cannot disagree with it in
       // production (issue #141 review r4).
       isFullReviewRound && rounds.length > 0 ? signalForRound(rounds.length, convergenceCounts, input.convergenceThreshold) : null,
-      input.jsonUrl,
-      scopeMetastasis
+      input.jsonUrl
     ),
     roundsMarker: roundsMarker(rounds),
     roundsSummary: roundsSummary(rounds, input.roundCount),
@@ -2273,10 +2257,9 @@ var post = async (input, ghApi = runGhApi) => {
   const emptyMechanicWouldBury = (route, incomplete) => route === "mechanic" && !incomplete && findings.findings.length === 0 && existingSticky !== null && priorIsFullReview(existingSticky.body);
   const priorRounds = existingSticky !== null ? parseRounds(existingSticky.body) : [];
   const priorSignal = existingSticky === null ? null : parseSignalMarker(existingSticky.body) ?? parseSurfaceSignal(parseFindingsMarker(existingSticky.body));
-  const findingsMarkerFor = (findings2, signal2, scopeMetastasis2) => {
-    const pointer = surfacedFindingsPointer(findings2, signal2, input.jsonUrl, scopeMetastasis2);
-    return signal2 !== null || priorSignal === null ? pointer : `${pointer}
-${signalMarker(priorSignal)}`;
+  const findingsMarkerFor = (findings2, signal2) => {
+    const pointer = surfacedFindingsPointer(findings2, signal2, input.jsonUrl);
+    return signal2 !== null || priorSignal === null ? pointer : joinSignalMarker(pointer, signalMarker(priorSignal));
   };
   const leaveInPlace = (message) => {
     process.stderr.write(
@@ -2430,8 +2413,8 @@ ${dropNote}` : ""}`,
         inlineDisposition: { kind: "no-envelope" },
         runUrl: input.runUrl,
         jsonUrl: input.jsonUrl,
-        // Same signal rule as the main path: only a completed-review doc carries the prior signal
-        // in its blob; an error-verdict doc preserves it in the compact marker instead.
+        // Same signal rule as the main path: a completed-review doc and an error-verdict doc alike
+        // ride the prior signal on the compact marker, never inside the blob.
         findingsPointer: findingsMarkerFor(
           findings,
           isReviewVerdict(findings.verdict) ? priorSignal : null
@@ -2490,19 +2473,18 @@ ${dropNote}` : ""}`,
     )
   ] : priorRounds;
   const signal = isRound ? signalForRound(roundNumber, computeRoundCounts(findings), input.convergenceThreshold) : thisIncomplete || !isReviewVerdict(findings.verdict) ? null : priorSignal;
-  const scopeMetastasis = isRound ? computeScopeMetastasis(rounds) : null;
-  const findingsMarker = findingsMarkerFor(findings, signal, scopeMetastasis);
-  const markerForm = findingsMarkerForm(
-    surfaceFindings(findings, signal, scopeMetastasis),
-    input.jsonUrl
-  );
+  const findingsMarker = findingsMarkerFor(findings, signal);
+  const markerForm = findingsMarkerForm(findings, input.jsonUrl);
+  const signalNote = signal !== null || priorSignal !== null ? " (the stop signal still rides the compact marker)" : "";
   if (markerForm === "link") {
     process.stderr.write(
-      "Warning: the findings-json marker exceeds the embed limit \u2014 degraded to the jsonUrl-link form; a decoding agent must fetch the artifact instead of the embedded JSON\n"
+      `Warning: the findings-json blob exceeds the embed limit \u2014 degraded to the jsonUrl-link form; a decoding agent must fetch the artifact for the findings${signalNote}
+`
     );
   } else if (markerForm === "omitted") {
     process.stderr.write(
-      "Warning: the findings-json marker exceeds the embed limit and no --json-url was given \u2014 the machine-readable channel is omitted from the posted surfaces\n"
+      `Warning: the findings-json blob exceeds the embed limit and no --json-url was given \u2014 the embedded findings seed is dropped from the posted surfaces${signalNote}
+`
     );
   }
   const commonRenderInput = {
@@ -2521,7 +2503,6 @@ ${dropNote}` : ""}`,
     sameRootNotes,
     answeredNotes: reRaisedNotes,
     answeredReRaiseNote: answeredDropNote,
-    scopeMetastasis,
     roundCount: signal?.round ?? priorSignal?.round ?? priorRounds.length,
     convergenceThreshold: input.convergenceThreshold,
     convergenceRound: isRound,
@@ -4166,6 +4147,8 @@ ${printableSchema(schemaPath)}
     }
   }
 });
+var isSurfaceStampedDoc = (doc) => typeof doc === "object" && doc !== null && !Array.isArray(doc) && doc["schema_version"] === SURFACE_SCHEMA_VERSION;
+var withoutScopeMetastasis = (doc) => typeof doc === "object" && doc !== null && !Array.isArray(doc) ? Object.fromEntries(Object.entries(doc).filter(([key2]) => key2 !== "scope_metastasis")) : doc;
 var seedDraftCmd = defineCommand({
   meta: {
     name: "seed-draft",
@@ -4239,7 +4222,10 @@ var seedDraftCmd = defineCommand({
       })();
       return typeof raw === "object" && raw !== null && "body" in raw && typeof raw.body === "string" ? raw.body : null;
     })();
-    const strippedPrior = priorBody === null ? null : stripSurfaceFields(parseFindingsMarker(priorBody));
+    const parsedPrior = priorBody === null ? null : parseFindingsMarker(priorBody);
+    const strippedPrior = parsedPrior === null ? null : stripSurfaceFields(
+      isSurfaceStampedDoc(parsedPrior) ? parsedPrior : withoutScopeMetastasis(parsedPrior)
+    );
     const priorFindings = (() => {
       if (strippedPrior === null || typeof strippedPrior !== "object" || Array.isArray(strippedPrior))
         return strippedPrior;