Files
Conflict_Checker/.hermes/plans/2026-08-20_brain-directed-clarification.md
T
woogi d37ac8c1c7
Docker Release / build-and-push (push) Successful in 1m8s
Docker Release / release (push) Skipped
feat: refocus on drawings — code/ADA gated off, drawing-integrity wave, Brain-directed clarification
- ENABLE_CODE_REVIEW flag (default off): skips code/ADA/jurisdiction review
  path in both pipelines; nothing deleted, one env flag to restore.
- Per-sheet Drawing Integrity QA wave (agent + classic, default on):
  dangling refs, on-sheet contradictions, dimension sanity, missing sheet
  essentials, tag hygiene. New DrawingIntegrityAgent + classic stage.
- Broadened conflict critic: intra-sheet + same-discipline contradictions,
  not just cross-discipline.
- Wave 6.5 Brain-directed clarification (bounded hub-and-spoke): Brain names
  uncertain findings, verify_evidence requests route through the wave-5b
  verifier; refuted findings suppressed. One planning call + capped verifies,
  single iteration. Shared _build_verify_scopes across 5b and 6.5.
- Config knobs, .env.example, frontend copy, tests (182 passing).
2026-08-20 15:10:32 -05:00

2.9 KiB

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) → EvidenceVerifierAgentapply_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.