# Plan: Brain-directed clarification pass (bounded hub-and-spoke)

Date: 2026-08-20
Branch: agent-mode

## Goal
Let the Brain actively chase weak/ambiguous findings instead of only judging
the finished pile once. Bounded, traceable, reuses the wave-5b verifier as the
"answer" channel. NOT a free agentic loop.

## Shape (agent pipeline)
Insert **wave 6.5: Brain-directed clarification** between the wave-6 Brain merge
and the review-gate / wave-7 branches, so BOTH paths benefit.

1. `BrainAgent.plan_clarifications(prioritized)` — one focused LLM call. Brain
   names findings it is unsure about and emits TYPED requests:
   `{issue_id, request_type, reason}`. v1 executes only `verify_evidence`;
   the router accepts other types but logs them as "planned, not executed"
   (extensible without a rewrite). Capped at `BRAIN_CLARIFY_MAX_REQUESTS`.
   Brain is told which findings already carry `verification` (from 5b) so it
   does not re-request them.
2. Route `verify_evidence` requests → build verify scopes for exactly those
   findings (reuse the SAME scope builder as wave 5b: fresh page images +
   hi-DPI evidence crops + text-layer oracle) → `EvidenceVerifierAgent` →
   `apply_verdicts(prioritized, ...)`. Refuted findings are annotated,
   demoted, removed from `prioritized`, and pushed into `memory["suppressed"]`
   (existing key — no memory-registry crash). Clarify decisions recorded in
   `memory["decisions"]`.
3. No second full Brain merge: Brain ASKED (step 1) and the verifier ANSWERED
   (step 2); the answer prunes/annotates the list. This keeps issue_ids stable
   for the review queue and adds at most 1 + N calls. One iteration only.

## Bounds / knobs (config.py, all env-overridable)
- `ENABLE_BRAIN_CLARIFY` (_flag, default true)
- `BRAIN_CLARIFY_MAX_REQUESTS` (default 8)
- reuse `AGENT_VERIFY_CONCURRENCY`, `VERIFY_MAX_TOKENS`,
  `AGENT_VERIFY_REASONING_EFFORT`, `AGENT_CONFLICT_MAX_IMAGES`,
  `VERIFY_HI_DPI_CROPS`.

## Reuse / refactor
- Extract the inline wave-5b verify-scope construction into
  `_build_verify_scopes(findings, targets, sheet_to_page, page_to_b64,
  page_to_text, page_words, pdf_path, prefix)` so wave 5b and wave 6.5 share
  it. Preserve wave-5b behavior exactly (its tests guard this).

## Classic pipeline
Out of scope for v1 — the verifier/crops live only in the agent path. Classic
keeps its single dedup_validate. Documented as agent-only.

## Tests
- `plan_clarifications` parses/caps/skips-already-verified (stub call_json).
- Router executes verify_evidence, ignores unknown types.
- Runner smoke: a low-confidence finding Brain flags gets refuted → moves to
  suppressed_issues; stub verifier.call_json (no live calls).

## Pitfalls to respect
- ProjectMemory keys are a closed registry — only use existing `suppressed` /
  `decisions`. (Skill defect C1.)
- Stub `backend.agents.verifier.call_json` in runner tests or it hits the net.
- Extractor stub sheets need >= 2 assertions or no clusters form.