refactor: improve assessment pipeline correctness (P0/P1/P2)

[arthurpanhku]

Summary

Four targeted fixes to the assessment pipeline, identified via first-principles review.

P0 — Citation traceability (orchestrator.py)

• _reviewer_agent prompt now instructs the LLM to declare exactly which chunk_ids it used (POL-N / HIS-N) and provide verbatim quotes.
• New _build_chunk_lookup + _resolve_citations_from_llm build SourceCitation objects from those declarations, replacing the prior behaviour that silently attached all passed-in KB chunks as citations regardless of whether the LLM actually consulted them.
• Falls back to the legacy all-chunks path only when the reviewer returns an empty sources array.

P0 — Semantic evidence extraction (orchestrator.py)

• _evidence_agent is now async and issues an LLM call to extract verbatim evidence lines scoped to skill.risk_focus, replacing a hardcoded keyword list that missed domain-specific terms ("data residency", "non-repudiation", "privacy by design", etc.).
• Old keyword scan extracted to _evidence_agent_keyword_fallback and retained as a fallback when the LLM call fails.

P1 — Semantic KB query seed (orchestrator.py)

• New _extract_query_seed scores document paragraphs by skill.risk_focus term frequency and greedily packs the highest-scoring ones into the KB query, replacing combined_input[:2000] which returned context from the document header regardless of relevance.

P1 — Large-document map-reduce (orchestrator.py)

• Documents longer than 12 000 chars are split into overlapping 10 000-char sections via _split_text_with_overlap.
• _draft_large_document runs _drafter_agent in parallel across sections and consolidates with a new _merge_drafts (MergeAgent) call, preventing silent truncation of appendices, exception clauses, and definitions that often appear at the end of security documents.

P2 — History storage granularity (kb/service.py)

• add_history_response now stores each RiskItem and ComplianceGap as a separate Document in the history vector store, replacing character-chunked JSON blobs that split objects mid-structure and made similarity retrieval semantically meaningless.

Test plan

• pytest tests/test_orchestrator.py tests/test_kb_history.py — 27 new/updated unit tests, all green locally (Python 3.11)
• Existing test test_orchestrator_uses_skill_prompt still passes (no breaking changes to public API)
• Manual: run a STRIDE assessment on a multi-page PDF and verify citations map to real KB chunks
• Manual: run on a document > 12 000 chars and confirm MergeAgent fires in logs

🤖 Generated with Claude Code