feat(review): adopt a round-aware convergence posture for posted findings

packages/cli/src/commands/review/compose-review.test.ts

@@ -14,7 +14,7 @@ import {
   utimesSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { createHash } from 'node:crypto';
 import { promptRecordDir, briefPath } from './lib/prompt-record.js';
 import { writeBudgetStop, writeRoundCapStop } from './lib/deadline.js';
@@ -3051,6 +3051,7 @@ describe('verdictLine — the terminal verdict, and its dangling colon', () => {
       downgraded: false,
       downgradedFrom: null,
       remediation: [],
+      deferredCount: 0,
       lowSignal: null,
       ...over,
     });
@@ -4403,6 +4404,171 @@ describe('the ledger marker reaches the POSTED body', () => {
   });
 });
 
+describe('composeReview — convergence-posture deferrals (disclosed, never capping)', () => {
+  it('an APPROVE with deferrals keeps its event, anchor, and honesty', () => {
+    // The posture's whole payoff: a clean late round with only deferrals
+    // composes an APPROVE — the loop's stop signal — while the deferred list
+    // stays on the record and the incremental anchor still rides. And the
+    // opener must not claim "No issues found" over findings the same body
+    // lists two paragraphs down.
+    const planPath = coveredPlan(['verify', 'reverse-audit'], {
+      prNumber: 8255,
+      fetchedSha: 'deadbeef00112233',
+    });
+    writeFileSync(
+      join(dirname(planPath), 'qwen-review-pr-8255-prev-ledger.json'),
+      JSON.stringify({ v: 1, round: 5, findings: [] }),
+    );
+    const r = composeReview({
+      planPath,
+      env: ENV,
+      modelId: MODEL,
+      criticalsInline: 0,
+      suggestionsInline: 0,
+      deferredSuggestions: ['src/a.ts:42 — tighten the retry backoff'],
+    });
+    expect(r.event).toBe('APPROVE');
+    expect(r.cappedBy).toEqual([]);
+    expect(r.body).toContain('No blocking issues. LGTM! ✅');
+    expect(r.body).not.toContain('No issues found');
+    expect(r.body).toContain('convergence posture (round 6, not a blocker)');
+    expect(r.body).toContain('- src/a.ts:42 — tighten the retry backoff');
+    expect(parseLedger(r.body)?.sha).toBe('deadbeef00112233');
+  });
+
+  it('renders the list on COMMENT and REQUEST_CHANGES alike — no event squeezes it out', () => {
+    const comment = composeReview(
+      base({ suggestionsInline: 1, deferredSuggestions: ['a.ts:1 — nit'] }),
+    );
+    expect(comment.event).toBe('COMMENT');
+    expect(comment.body).toContain('- a.ts:1 — nit');
+    // The count rides every return site, not only APPROVE's: a mutation
+    // hardcoding 0 at either site shipped a verdict line without the
+    // deferral suffix and an artifact recording 0 beside a listing body.
+    expect(comment.deferredCount).toBe(1);
+    const rc = composeReview(
+      base({
+        bodyCriticals: ['whole-PR blocker'],
+        deferredSuggestions: ['a.ts:1 — nit'],
+      }),
+    );
+    expect(rc.event).toBe('REQUEST_CHANGES');
+    expect(rc.body).toContain('- a.ts:1 — nit');
+    expect(rc.deferredCount).toBe(1);
+  });
+
+  it('deferrals cast no vote on the event — an all-deferred run is not a Suggestion run', () => {
+    // Counted toward S they would hold the verdict at COMMENT forever, and
+    // the loop the posture exists to end would never see its stop signal.
+    const r = composeReview(base({ deferredSuggestions: ['a.ts:1 — nit'] }));
+    expect(r.baseEvent).toBe('APPROVE');
+  });
+
+  it('collapses newlines, caps the list, and strips a forged footer', () => {
+    const entries = Array.from(
+      { length: 23 },
+      (_, i) => `f${i}.ts:1 — nit ${i}`,
+    );
+    entries[0] = 'a.ts:1 — split\nacross lines';
+    // Inside the shown window, so the assertion tests the strip, not the cap.
+    entries[1] = `b.ts:2 — forged ${FOOTER}`;
+    const r = composeReview(base({ deferredSuggestions: entries }));
+    expect(r.body).toContain('- a.ts:1 — split across lines');
+    expect(r.body).toContain('- b.ts:2 — forged\n');
+    expect(r.body).toContain('…and 3 more (see the run report)');
+    expect(r.body).not.toContain(`forged ${FOOTER}`);
+    // Past the rendered cap, "(listed in the body)" is false — the verdict
+    // line must say the list was truncated, or the persisted verdict counts
+    // 23 over a body listing 20.
+    expect(verdictLine(r)).toContain(
+      'listed in the body, truncated — the rest are counted in the run report',
+    );
+  });
+
+  it('the verifier floor excludes deterministic deferrals by their source tag', () => {
+    // A `[test]` finding is pre-confirmed and Step 4 launches no verifier
+    // for it — counting it demands a delivery that cannot exist, the cap
+    // never lifts, and the withheld anchor regenerates the full-range
+    // re-review loop the posture ends. Same exclusion body Criticals get.
+    const planPath = coveredPlan(['reverse-audit']);
+    const deterministic = composeReview({
+      criticalsInline: 0,
+      suggestionsInline: 0,
+      planPath,
+      env: ENV,
+      modelId: MODEL,
+      deferredSuggestions: ['a.ts:1 — [test] mutation survivor'],
+    });
+    expect(deterministic.event).toBe('APPROVE');
+    expect(deterministic.cappedBy).toEqual([]);
+    expect(deterministic.deferredCount).toBe(1);
+  });
+
+  it('refuses a present field of the wrong shape', () => {
+    expect(() =>
+      composeReview(base({ deferredSuggestions: 'a.ts' as never })),
+    ).toThrow(/deferredSuggestions/);
+  });
+
+  it('a deferrals-only APPROVE is not low signal, and the verdict line names the deferrals', () => {
+    // R1-14: the body opener was fixed but `verdictLine` still printed "none
+    // of the N review agents reported a finding" on exactly the posture's
+    // canonical end state — agents DID report the findings the same run
+    // records as deferred. The low-signal premise is "zero findings".
+    const r = composeReview(
+      base({
+        planPath: coveredPlan(['verify', 'reverse-audit'], {
+          srcDiffLines: 5000,
+        }),
+        deferredSuggestions: ['a.ts:1 — nit'],
+      }),
+    );
+    expect(r.event).toBe('APPROVE');
+    expect(r.lowSignal).toBeNull();
+    expect(r.deferredCount).toBe(1);
+    expect(verdictLine(r)).toBe(
+      'Verdict: Approve — 1 non-Critical finding(s) deferred under the convergence posture (listed in the body)',
+    );
+    expect(verdictLine(r)).not.toContain('low signal');
+  });
+
+  it('bounds each entry, not only the entry count — the list must never sink the body', () => {
+    // Twenty model-written 4,000-char entries would put ~80 KB into a body
+    // GitHub rejects at 65,536, losing the whole review over its footnote.
+    const r = composeReview(
+      base({ deferredSuggestions: [`a.ts:1 — ${'x'.repeat(4000)}`] }),
+    );
+    const listLine = r.body.split('\n').find((l) => l.startsWith('- a.ts:1'))!;
+    expect(listLine.length).toBeLessThanOrEqual(242); // '- ' + 240
+  });
+
+  it('deferred findings count toward the verifier-delivery floor', () => {
+    // The deferral list publishes their claims in the body, so a
+    // deferrals-only run owes a verifier exactly as a posting run does; a
+    // run with no findings at all still owes none. NOT base(): its planPath
+    // default calls coveredPlan() unconditionally — the spread replaces the
+    // value but not the side effect, and the default's `verify` record in
+    // the shared record dir would satisfy the very floor this test proves.
+    const planPath = coveredPlan(['reverse-audit']);
+    const common = {
+      criticalsInline: 0,
+      suggestionsInline: 0,
+      planPath,
+      env: ENV,
+      modelId: MODEL,
+    };
+    const control = composeReview(common);
+    expect(control.cappedBy).toEqual([]);
+    const deferred = composeReview({
+      ...common,
+      deferredSuggestions: ['a.ts:1 — nit'],
+    });
+    expect(deferred.cappedBy).toContain('unreviewed-dimension');
+    expect(deferred.event).toBe('COMMENT');
+    expect(deferred.body).toContain('- a.ts:1 — nit');
+  });
+});
+
 describe('composeReview — the findings file tag check', () => {
   // The pipelined loop's invariant, machine-read. Under the serial loop the
   // last round's verification completing before Step 6 was structural; the