@event4u/agent-config 2.12.0 → 2.13.0

package/scripts/ai_council/orchestrator.py

@@ -32,6 +32,18 @@ from scripts.ai_council.clients import (
     CouncilResponse,
     ExternalAIClient,
 )
+from scripts.ai_council.consensus import (
+    ConsensusBucket,
+    ConsensusMetadata,
+    Finding,
+    FindingScore,
+    aggregate_scores,
+    anonymize_findings,
+    anonymize_responses,
+    bucket_by_threshold,
+    parse_findings_response,
+    parse_scores_response,
+)
 from scripts.ai_council.pricing import (
     CostEstimate,
     PriceTable,
@@ -39,7 +51,16 @@ from scripts.ai_council.pricing import (
     estimate_input_tokens,
 )
 from scripts.ai_council.project_context import ProjectContext
-from scripts.ai_council.prompts import system_prompt_for
+from scripts.ai_council.advisors import AdvisorPlan
+from scripts.ai_council.prompts import (
+    advisor_system_prompt,
+    build_extraction_user_prompt,
+    build_peer_review_user_prompt,
+    build_scoring_user_prompt,
+    peer_review_synthesis_addendum,
+    synthesis_template,
+    system_prompt_for,
+)
 
 
 @dataclass
@@ -85,21 +106,41 @@ def estimate(
     *,
     project: ProjectContext | None = None,
     original_ask: str = "",
+    advisor_plans: dict[str, AdvisorPlan] | None = None,
 ) -> list[CostEstimate]:
     """Return a pre-call cost estimate per member, in input order.
 
     `project` and `original_ask` are passed through to
     `system_prompt_for()` so the estimate covers the handoff preamble
     bytes too. Both default to v1-shape (no preamble extension).
+
+    `advisor_plans` (Phase 6) — when a member's name has a plan, the
+    estimate uses the advisor persona system prompt (typically larger
+    than the bare mode addendum). The cost estimator must mirror
+    `_run_round` exactly so the pre-call preview never under-states
+    the advisor-mode bill.
     """
-    sys_prompt = system_prompt_for(
+    plans = advisor_plans or {}
+    base_user_tokens = estimate_input_tokens(question.user_prompt)
+    base_sys = system_prompt_for(
         question.mode, project=project, original_ask=original_ask,
     )
-    input_tokens = estimate_input_tokens(question.user_prompt) + estimate_input_tokens(sys_prompt)
-    return [
-        estimate_cost(m.name, m.model, input_tokens, question.max_tokens, table)
-        for m in members
-    ]
+    base_sys_tokens = estimate_input_tokens(base_sys)
+    estimates: list[CostEstimate] = []
+    for m in members:
+        plan = plans.get(m.name)
+        if plan is None:
+            sys_tokens = base_sys_tokens
+        else:
+            sys_prompt = advisor_system_prompt(
+                plan.persona_text, project=project, original_ask=original_ask,
+            )
+            sys_tokens = estimate_input_tokens(sys_prompt)
+        input_tokens = base_user_tokens + sys_tokens
+        estimates.append(
+            estimate_cost(m.name, m.model, input_tokens, question.max_tokens, table),
+        )
+    return estimates
 
 
 def consult(
@@ -113,6 +154,7 @@ def consult(
     original_ask: str = "",
     rounds: int = 1,
     on_round_complete: Callable[[int, list[CouncilResponse]], None] | None = None,
+    advisor_plans: dict[str, AdvisorPlan] | None = None,
 ) -> list[CouncilResponse]:
     """Sequentially fan out `question` to every enabled member.
 
@@ -133,6 +175,9 @@ def consult(
       accumulate across rounds. Returns the FINAL round's responses;
       use `on_round_complete(round_idx, responses)` to capture
       intermediate rounds.
+    - `advisor_plans` (Phase 6) keyed by provider name swaps the
+      member's system prompt for the advisor persona via
+      `advisor_system_prompt()`. Replace-mode: no extra calls.
     """
     if rounds < 1:
         raise ValueError(f"rounds must be >= 1 (got {rounds})")
@@ -162,6 +207,7 @@ def consult(
             members, round_question, budget, spent,
             table=table, on_overrun=on_overrun,
             project=project, original_ask=original_ask,
+            advisor_plans=advisor_plans,
         )
         if on_round_complete is not None:
             on_round_complete(round_idx, last_results)
@@ -183,14 +229,29 @@ def _run_round(
     on_overrun: OnOverrunCallback | None,
     project: ProjectContext | None,
     original_ask: str,
+    advisor_plans: dict[str, AdvisorPlan] | None = None,
 ) -> list[CouncilResponse]:
     """Run a single round; mutate `spent` with cumulative totals."""
-    system_prompt = system_prompt_for(
+    plans = advisor_plans or {}
+    base_system_prompt = system_prompt_for(
         question.mode, project=project, original_ask=original_ask,
     )
+
+    def _system_prompt_for_member(m: ExternalAIClient) -> str:
+        plan = plans.get(m.name)
+        if plan is None:
+            return base_system_prompt
+        return advisor_system_prompt(
+            plan.persona_text, project=project, original_ask=original_ask,
+        )
+
     results: list[CouncilResponse] = []
     estimates = (
-        estimate(question, members, table, project=project, original_ask=original_ask)
+        estimate(
+            question, members, table,
+            project=project, original_ask=original_ask,
+            advisor_plans=advisor_plans,
+        )
         if table is not None
         else None
     )
@@ -202,7 +263,10 @@ def _run_round(
         # observability, but no projection / budget breach can apply.
         if not getattr(member, "billable", True):
             try:
-                response = member.ask(system_prompt, question.user_prompt, question.max_tokens)
+                response = member.ask(
+                    _system_prompt_for_member(member),
+                    question.user_prompt, question.max_tokens,
+                )
             except Exception as exc:  # noqa: BLE001 - last-resort safety net
                 response = CouncilResponse(
                     provider=member.name, model=member.model, text="",
@@ -265,7 +329,10 @@ def _run_round(
 
         # ── actual call ──────────────────────────────────────────────
         try:
-            response = member.ask(system_prompt, question.user_prompt, question.max_tokens)
+            response = member.ask(
+                _system_prompt_for_member(member),
+                question.user_prompt, question.max_tokens,
+            )
         except Exception as exc:  # noqa: BLE001 - last-resort safety net
             response = CouncilResponse(
                 provider=member.name, model=member.model, text="",
@@ -337,9 +404,491 @@ def _augment_for_next_round(
     )
 
 
-def render(responses: list[CouncilResponse]) -> str:
-    """Render stacked sections + a Convergence/Divergence summary slot."""
+@dataclass
+class DebateCheckpoint:
+    """Snapshot passed to the continue-prompt callback between rounds.
+
+    Phase 7 progressive-disclosure contract — the orchestrator pauses
+    after each completed round, builds this checkpoint, and asks the
+    caller whether to continue. Returning False stops the debate
+    gracefully (caller receives every completed round).
+    """
+
+    completed_round: int  # 1-based index of the round just finished
+    total_planned_rounds: int
+    cost_so_far_usd: float
+    next_round_estimate_usd: float
+    last_round_responses: list[CouncilResponse]
+
+
+class DebateCapExceeded(RuntimeError):
+    """Raised when projected next-round spend would breach the budget cap.
+
+    The CLI catches this *after* writing the partial artefact, so the
+    user always has a recoverable trail of the rounds that completed
+    before the cap fired.
+    """
+
+    def __init__(
+        self, *,
+        completed_round: int,
+        cost_so_far: float,
+        next_estimate: float,
+        cap: float,
+    ) -> None:
+        self.completed_round = completed_round
+        self.cost_so_far = cost_so_far
+        self.next_estimate = next_estimate
+        self.cap = cap
+        super().__init__(
+            f"Debate hard-cap: round {completed_round + 1} would push spend "
+            f"to ${cost_so_far + next_estimate:.4f} (cap=${cap:.4f}); "
+            f"stopping after round {completed_round}."
+        )
+
+
+# Continue-prompt callback. Receives a DebateCheckpoint, returns True to
+# proceed with the next round, False to stop gracefully.
+DebateContinuePrompt = Callable[[DebateCheckpoint], bool]
+
+
+def _augment_for_debate_round(
+    original_prompt: str,
+    prior_responses: list[CouncilResponse],
+    next_round_number: int,
+) -> str:
+    """Build the round-N user prompt for a debate — rebuttal framing.
+
+    Same anonymisation rules as `_augment_for_next_round` (Iron Law of
+    Neutrality § multi-round): provider/model identifiers stripped,
+    "Reviewer A / B / C…" labels assigned in input order, errors
+    skipped. The instruction block is debate-specific: each reviewer
+    is asked to identify the strongest opposing position and write a
+    rebuttal, NOT to find common ground.
+    """
     blocks: list[str] = []
+    label_idx = 0
+    for r in prior_responses:
+        if r.error or not r.text.strip():
+            continue
+        label = chr(ord("A") + label_idx)
+        label_idx += 1
+        blocks.append(f"### Reviewer {label}\n\n{r.text.strip()}")
+    if not blocks:
+        return original_prompt
+    prior_block = "\n\n".join(blocks)
+    return (
+        f"{original_prompt}\n\n"
+        f"---\n\n"
+        f"## Prior round positions (round {next_round_number - 1})\n\n"
+        f"You are now in round {next_round_number} of a structured\n"
+        f"debate. Below are anonymised positions from independent\n"
+        f"reviewers in the previous round. You do NOT know which model\n"
+        f"produced which position.\n\n"
+        f"Identify the SINGLE strongest opposing position and write a\n"
+        f"rebuttal addressed at its strongest steel-manned form. Do NOT\n"
+        f"search for common ground — name the load-bearing flaw the\n"
+        f"opposing reviewer missed and state the evidence behind your\n"
+        f"counter-position.\n\n"
+        f"{prior_block}"
+    )
+
+
+def run_debate(
+    members: list[ExternalAIClient],
+    question: CouncilQuestion,
+    *,
+    budget: CostBudget | None = None,
+    table: PriceTable | None = None,
+    on_overrun: OnOverrunCallback | None = None,
+    project: ProjectContext | None = None,
+    original_ask: str = "",
+    max_rounds: int = 2,
+    on_round_complete: Callable[[int, list[CouncilResponse]], None] | None = None,
+    on_continue: DebateContinuePrompt | None = None,
+    advisor_plans: dict[str, AdvisorPlan] | None = None,
+    seed_round_1: list[CouncilResponse] | None = None,
+) -> list[list[CouncilResponse]]:
+    """Run a structured multi-round debate with progressive disclosure.
+
+    Returns every completed round in order — caller persists each
+    round incrementally via `on_round_complete` for crash safety.
+
+    Round 1: each member produces an initial position. When
+    `seed_round_1` is provided, it is reused verbatim (no calls) so
+    `/council debate --continue-as-debate` can pivot from an existing
+    `/council default` session.
+
+    Round 2+: `_augment_for_debate_round` wraps the original prompt
+    with anonymised prior positions and asks each member for a
+    rebuttal addressed at the strongest opposing view.
+
+    Between rounds: `on_continue(checkpoint)` is consulted. Returning
+    False stops the debate; the caller receives every completed round.
+    `None` (the default) auto-continues — the CLI wires its
+    interactive y/N prompt here, `--auto-continue` passes `None`.
+
+    Hard cap: before kicking off round N+1, the orchestrator compares
+    `spent_usd + next_round_estimate` to `budget.max_total_usd`. A
+    projected breach raises `DebateCapExceeded`; the CLI catches it
+    after persisting the partial debate.
+    """
+    if max_rounds < 1:
+        raise ValueError(f"max_rounds must be >= 1 (got {max_rounds})")
+    if not members:
+        return []
+    budget = budget or CostBudget()
+    if len(members) > budget.max_calls:
+        raise ValueError(
+            f"Debate has {len(members)} members but budget caps at "
+            f"{budget.max_calls} calls."
+        )
+
+    spent: dict[str, float] = {"input": 0, "output": 0, "usd": 0.0}
+    all_rounds: list[list[CouncilResponse]] = []
+    current_user_prompt = question.user_prompt
+
+    for round_idx in range(max_rounds):
+        round_number = round_idx + 1
+        if round_idx == 0 and seed_round_1 is not None:
+            # Pivot from /council default — reuse the existing round 1
+            # verbatim. No calls billed; spend stays at $0 until round 2.
+            results = list(seed_round_1)
+        else:
+            round_question = (
+                question if round_idx == 0
+                else CouncilQuestion(
+                    mode=question.mode,
+                    user_prompt=current_user_prompt,
+                    max_tokens=question.max_tokens,
+                )
+            )
+            results = _run_round(
+                members, round_question, budget, spent,
+                table=table, on_overrun=on_overrun,
+                project=project, original_ask=original_ask,
+                advisor_plans=advisor_plans,
+            )
+
+        all_rounds.append(results)
+        if on_round_complete is not None:
+            on_round_complete(round_number, results)
+
+        # Prep the user-prompt for the next round so the cost estimate
+        # below covers the augmented bytes.
+        if round_idx + 1 < max_rounds:
+            current_user_prompt = _augment_for_debate_round(
+                question.user_prompt, results, round_number + 1,
+            )
+            # Hard-cap + continue-prompt gating before kicking off N+1.
+            if table is not None:
+                next_question = CouncilQuestion(
+                    mode=question.mode,
+                    user_prompt=current_user_prompt,
+                    max_tokens=question.max_tokens,
+                )
+                next_estimates = estimate(
+                    next_question, members, table,
+                    project=project, original_ask=original_ask,
+                    advisor_plans=advisor_plans,
+                )
+                next_round_usd = sum(e.total_usd for e in next_estimates)
+            else:
+                next_round_usd = 0.0
+
+            if (
+                budget.max_total_usd > 0
+                and spent["usd"] + next_round_usd > budget.max_total_usd
+            ):
+                raise DebateCapExceeded(
+                    completed_round=round_number,
+                    cost_so_far=spent["usd"],
+                    next_estimate=next_round_usd,
+                    cap=budget.max_total_usd,
+                )
+
+            if on_continue is not None:
+                checkpoint = DebateCheckpoint(
+                    completed_round=round_number,
+                    total_planned_rounds=max_rounds,
+                    cost_so_far_usd=spent["usd"],
+                    next_round_estimate_usd=next_round_usd,
+                    last_round_responses=results,
+                )
+                if not on_continue(checkpoint):
+                    return all_rounds
+
+    return all_rounds
+
+
+@dataclass
+class PeerReviewResult:
+    """Bundle returned by `run_peer_review()` (Phase 5 / F1).
+
+    `responses` carries the per-reviewer critiques. `label_to_source`
+    is the anonymisation map captured server-side so the audit-trail
+    JSON can rehydrate it without leaking provider identity to the
+    member at prompt time.
+
+    `persona_labels` is the (optional) Phase 6 / Step 3a wiring: when
+    the deliberation was an advisor-mode run, the source → persona
+    map flows through to the renderer so peer-review output can render
+    as `Response A (Contrarian)`. Plain-member runs leave it empty.
+    """
+
+    responses: list[CouncilResponse]
+    label_to_source: dict[str, str]
+    persona_labels: dict[str, str]
+
+
+def run_peer_review(
+    members: list[ExternalAIClient],
+    deliberation_responses: list[CouncilResponse],
+    *,
+    budget: CostBudget | None = None,
+    table: PriceTable | None = None,
+    on_overrun: OnOverrunCallback | None = None,
+    project: ProjectContext | None = None,
+    original_ask: str = "",
+    max_tokens: int = DEFAULT_MAX_TOKENS,
+    persona_labels: dict[str, str] | None = None,
+) -> PeerReviewResult:
+    """Karpathy peer-review pass (Phase 5 / F1).
+
+    After the final deliberation round, each member sees the OTHER
+    members' deliberation outputs under neutral `Response-A` labels
+    (provider identity stripped; advisor persona labels preserved per
+    Phase 6 Step 3a) and emits a Karpathy-style critique:
+    strongest / weakest blind spot / what all missed / refinement.
+
+    Members never see their own response — the orchestrator filters
+    self before building the anonymised prompt. Errors in one member's
+    pass tag that member but never abort the round.
+
+    Cost gates flow through `consult([member], ...)`, so the same
+    budget + daily-ledger semantics as deliberation apply.
+    """
+    if not members or not deliberation_responses:
+        return PeerReviewResult(
+            responses=[], label_to_source={}, persona_labels={},
+        )
+
+    member_by_name = {m.name: m for m in members}
+    # ── source map: deliberation responses keyed by `provider:model` ─
+    # Errors and empty bodies are skipped — they leak nothing useful
+    # and would clutter the anonymised prompt with blanks.
+    by_source: dict[str, CouncilResponse] = {}
+    for r in deliberation_responses:
+        if r.error or not r.text.strip():
+            continue
+        source = f"{r.provider}:{r.model}"
+        by_source[source] = r
+
+    if len(by_source) < 2:
+        # Peer-review needs ≥ 2 distinct deliberation outputs (a
+        # reviewer with nothing else to review is a no-op).
+        return PeerReviewResult(
+            responses=[], label_to_source={}, persona_labels={},
+        )
+
+    persona_labels = dict(persona_labels or {})
+    review_responses: list[CouncilResponse] = []
+    # ── final label_to_source map captured from the LAST member call
+    # so the renderer / JSON dump has the deterministic A/B mapping.
+    # Each member sees a different N-1 subset (self filtered), but the
+    # ordering of `by_source` stays stable, so the label assignment is
+    # deterministic per artefact run.
+    last_label_to_source: dict[str, str] = {}
+
+    for reviewer in members:
+        scorer = f"{reviewer.name}:{reviewer.model}"
+        if reviewer.name not in member_by_name:
+            continue
+        others_pairs = [
+            (src, resp.text) for src, resp in by_source.items() if src != scorer
+        ]
+        if len(others_pairs) == 0:
+            continue
+        anon_text, label_to_source = anonymize_responses(
+            others_pairs, persona_labels=persona_labels,
+        )
+        if not anon_text:
+            continue
+        last_label_to_source = label_to_source
+        question = CouncilQuestion(
+            mode="prompt",
+            user_prompt=build_peer_review_user_prompt(anon_text),
+            max_tokens=max_tokens,
+        )
+        reviewed = consult(
+            [reviewer], question,
+            budget=budget, table=table, on_overrun=on_overrun,
+            project=project, original_ask=original_ask,
+        )
+        review_responses.extend(reviewed)
+
+    return PeerReviewResult(
+        responses=review_responses,
+        label_to_source=last_label_to_source,
+        persona_labels=persona_labels,
+    )
+
+
+@dataclass
+class ConsensusResult:
+    """Bundle returned by `run_consensus_scoring()`.
+
+    `bucket` is renderer-ready; `findings`, `scores`, and `metadata`
+    are kept for audit-trail JSON (council-sessions/*.json).
+    """
+
+    bucket: ConsensusBucket
+    findings: list[Finding]
+    scores: list[FindingScore]
+    metadata: dict[str, ConsensusMetadata]
+    extraction_responses: list[CouncilResponse]
+    scoring_responses: list[CouncilResponse]
+
+
+def run_consensus_scoring(
+    members: list[ExternalAIClient],
+    deliberation_responses: list[CouncilResponse],
+    *,
+    budget: CostBudget | None = None,
+    table: PriceTable | None = None,
+    on_overrun: OnOverrunCallback | None = None,
+    project: ProjectContext | None = None,
+    original_ask: str = "",
+    max_tokens: int = DEFAULT_MAX_TOKENS,
+    strong_threshold: float = 0.7,
+    minority_threshold: float = 0.4,
+) -> ConsensusResult:
+    """Two-pass consensus round (Phase 4 / F3).
+
+    Pass 1 — extraction: each member re-emits its own deliberation as
+    a JSON array of `{id, text}` findings. Pass 2 — scoring: each
+    member sees the *other* members' findings under anonymous labels
+    and rates them 1-10 + agree/disagree + reason.
+
+    The cost budget is shared across both passes; the daily ledger
+    receives both. Errors in one member's extraction or scoring tag
+    that member but never abort the round.
+    """
+    if not members or not deliberation_responses:
+        return ConsensusResult(
+            bucket=ConsensusBucket(), findings=[], scores=[], metadata={},
+            extraction_responses=[], scoring_responses=[],
+        )
+
+    # ── Pass 1: extraction ──────────────────────────────────────────
+    member_by_name = {m.name: m for m in members}
+    extraction_responses: list[CouncilResponse] = []
+    all_findings: list[Finding] = []
+    for resp in deliberation_responses:
+        member = member_by_name.get(resp.provider)
+        if member is None or resp.error or not resp.text.strip():
+            continue
+        question = CouncilQuestion(
+            mode="prompt",
+            user_prompt=build_extraction_user_prompt(resp.text),
+            max_tokens=max_tokens,
+        )
+        extracted = consult(
+            [member], question,
+            budget=budget, table=table, on_overrun=on_overrun,
+            project=project, original_ask=original_ask,
+        )
+        extraction_responses.extend(extracted)
+        if not extracted or extracted[0].error:
+            continue
+        source = f"{member.name}:{member.model}"
+        all_findings.extend(
+            parse_findings_response(extracted[0].text, source=source),
+        )
+
+    if not all_findings:
+        return ConsensusResult(
+            bucket=ConsensusBucket(), findings=[], scores=[], metadata={},
+            extraction_responses=extraction_responses, scoring_responses=[],
+        )
+
+    # ── Pass 2: scoring (each member rates the OTHERS' findings) ────
+    scoring_responses: list[CouncilResponse] = []
+    all_scores: list[FindingScore] = []
+    for member in members:
+        scorer = f"{member.name}:{member.model}"
+        others = [f for f in all_findings if f.source != scorer]
+        if not others:
+            continue
+        anon = anonymize_findings(others)
+        label_to_id = {label: f.id for label, f in anon.items()}
+        anon_text = {label: f.text for label, f in anon.items()}
+        question = CouncilQuestion(
+            mode="prompt",
+            user_prompt=build_scoring_user_prompt(anon_text),
+            max_tokens=max_tokens,
+        )
+        scored = consult(
+            [member], question,
+            budget=budget, table=table, on_overrun=on_overrun,
+            project=project, original_ask=original_ask,
+        )
+        scoring_responses.extend(scored)
+        if not scored or scored[0].error:
+            continue
+        for s in parse_scores_response(scored[0].text, scorer=scorer):
+            real_id = label_to_id.get(s.finding_id)
+            if real_id is None:
+                continue
+            all_scores.append(FindingScore(
+                finding_id=real_id, scorer=s.scorer, score=s.score,
+                agree=s.agree, reason=s.reason,
+            ))
+
+    metadata = aggregate_scores(all_findings, all_scores)
+    bucket = bucket_by_threshold(
+        all_findings, metadata,
+        strong=strong_threshold, minority=minority_threshold,
+    )
+    return ConsensusResult(
+        bucket=bucket, findings=all_findings, scores=all_scores,
+        metadata=metadata, extraction_responses=extraction_responses,
+        scoring_responses=scoring_responses,
+    )
+
+
+def render(
+    responses: list[CouncilResponse],
+    *,
+    mode: str | None = None,
+    prose_synthesis: bool | None = None,
+    consensus: ConsensusResult | None = None,
+    peer_review: PeerReviewResult | None = None,
+) -> str:
+    """Render stacked sections + a lens-aware synthesis prompt slot.
+
+    `mode` selects the synthesis template from `prompts.synthesis_template`.
+    `None` collapses to the default decision-lens template (back-compat).
+
+    `prose_synthesis` is the R4 Q4 escape hatch:
+      - `True`  → force creative-lens passthrough (bare slot) regardless of mode
+      - `False` → force decision-lens default template even on creative lenses
+      - `None`  → honour the lens default from the table
+
+    `consensus` (Phase 4 / F3) prepends Strong Consensus / Findings /
+    Minority Views sections when the analysis lens scored its findings.
+
+    `peer_review` (Phase 5 / F1) appends a Peer-Review block listing
+    each member's critique (under Reviewer-A / Reviewer-B labels, in
+    member input order so the audit trail is deterministic) and
+    extends the synthesis template with the
+    `Peer-Review-Surfaced Blind Spots` addendum.
+    """
+    blocks: list[str] = []
+    if consensus is not None and (
+        consensus.bucket.strong or consensus.bucket.findings or consensus.bucket.minority
+    ):
+        blocks.append(_render_consensus(consensus.bucket))
     for r in responses:
         header = f"## {r.provider} · {r.model}"
         if r.error:
@@ -350,5 +899,70 @@ def render(responses: list[CouncilResponse]) -> str:
             f"{r.latency_ms} ms*"
         )
         blocks.append(f"{header}\n\n{meta}\n\n{r.text}")
-    blocks.append("## Convergence / Divergence\n\n*to be summarised by the host agent*")
+    if peer_review is not None and peer_review.responses:
+        blocks.append(_render_peer_review(peer_review))
+    if prose_synthesis is True:
+        template = ""
+    elif prose_synthesis is False:
+        template = synthesis_template("default")
+    else:
+        template = synthesis_template(mode)
+    if peer_review is not None and peer_review.responses:
+        addendum = peer_review_synthesis_addendum()
+        template = f"{template}\n{addendum}" if template else addendum.lstrip()
+    if template:
+        body = template
+    else:
+        body = "*to be summarised by the host agent*"
+    blocks.append(f"## Convergence / Divergence\n\n{body}")
     return "\n\n---\n\n".join(blocks)
+
+
+def _render_peer_review(peer_review: PeerReviewResult) -> str:
+    """Render the peer-review block under deterministic Reviewer labels.
+
+    Each successful reviewer gets a `### Reviewer X` sub-section. Errors
+    keep their slot (so the audit trail still surfaces the breach) but
+    render `ERROR: <tag>` instead of the prompt body.
+    """
+    lines = ["## Peer-Review (Karpathy)"]
+    label_idx = 0
+    for r in peer_review.responses:
+        label = chr(ord("A") + label_idx)
+        label_idx += 1
+        if r.error:
+            lines.append(f"### Reviewer {label}\n\n*ERROR:* `{r.error}`")
+            continue
+        lines.append(f"### Reviewer {label}\n\n{r.text.strip()}")
+    return "\n\n".join(lines)
+
+
+def _render_consensus(bucket: ConsensusBucket) -> str:
+    """Render Strong / Findings / Minority sections in renderer order."""
+    parts: list[str] = []
+    if bucket.strong:
+        parts.append("## Strong Consensus\n\n" + _render_bucket(bucket.strong))
+    if bucket.findings:
+        parts.append("## Findings\n\n" + _render_bucket(bucket.findings))
+    if bucket.minority:
+        parts.append(
+            "## Minority Views\n\n"
+            "*Sub-threshold by consensus; kept for audit trail.*\n\n"
+            + _render_bucket(bucket.minority)
+        )
+    return "\n\n".join(parts)
+
+
+def _render_bucket(
+    items: list[tuple[Finding, ConsensusMetadata]],
+) -> str:
+    lines: list[str] = []
+    for f, m in items:
+        badge = (
+            f"strength {m.consensus_strength:.2f} · "
+            f"mean {m.mean_score:.1f}/10 · "
+            f"{len(m.scorers)} scorers · "
+            f"{m.dissent_count} dissent"
+        )
+        lines.append(f"- **{f.id}** — {f.text}  \n  _{badge}_")
+    return "\n".join(lines)