feat: research integrity layers 2+3 (closes #8)

[dep0we]

Summary

Implements spec/13 Layers 2 and 3 — source-grounded eval and the research-log-per-response trail. Layer 1 (citation requirements via persona + rubric) was already done in v0.1. Together, the three layers make agent factual accuracy auditable: every claim in a response can be traced back to the helper that produced it and the source it came from.

This PR is stacked on `feat/helper-provenance` (PR #20) — Layer 3 depends on the helper provenance plumbing landing first. Merge order: #15 → #16 → #17 → #18 → #19 → #20 → this.

What landed

Layer 2 — Source-grounded eval (`atomic_agents/eval.py`)

• `_build_judge_prompt` — when a test declares `expected_facts`, append a "Factual accuracy check" section instructing the judge to verify each fact (`stated_in_response`, `value_correct`, `cited`) and emit a `factual_checks` array in its JSON response.
• `_render_factual_check_section` — builds the addendum: one bullet per expected fact + the JSON template the judge follows.
• `compute_factual_accuracy_from_checks(checks)` (module-level for testability) — derive a 1–5 dimension score from a list of factual_checks:
  • Verified (stated AND value_correct AND cited) → full credit
  • Stated + correct but uncited → half credit
  • Stated + wrong value → no credit
  • Score = `round(5 × verified / total)`, clamped to [1, 5]
  • Empty checks → `None` (no signal to score from)
• `_compute_weighted_score` — when `factual_accuracy` is in the rubric weights but the judge didn't return a numeric score for it, derive one from `factual_checks`. Judge's numeric score takes priority when present (LLM may apply nuance the bare proportion misses).

Layer 3 — Research log per response (`atomic_agents/agent.py`)

• `_helpers_this_run` — in-memory list of helper-call rollups; reset at the start of each `call()`, appended to by `helper_call()`.
• `helper_call` — after logging the helper run line, append a rollup entry (model, summary, cost, latency, sources_summarized, provenance_preserved) to the parent's `_helpers_this_run`.
• `agent.call` — when finishing, embed the rollup as `helper_provenance` in the parent's run log record. Field is omitted when no helpers were called during the run, so log shape stays unchanged for reactive agents that don't fan out.

Example: log shape after a parent run that fanned out to two helpers

```json
{
"ts": "2026-05-08T11:32:00-05:00",
"trigger": "skill",
"model": "claude-opus-4-7-20260101",
"input_tokens": 4102,
"output_tokens": 892,
"cost_usd": 0.1287,
"status": "ok",
"summary": "Q1 bonus allocation question",
"run_id": "run-...",
"helper_provenance": [
{
"model": "claude-haiku-4-5-20251001",
"summary": "Summarize CPA memo",
"cost_usd": 0.00094,
"latency_ms": 240,
"sources_summarized": ["/docs/finance/cpa/2026-05-tax-mid-year.md"],
"provenance_preserved": true
},
{
"model": "claude-haiku-4-5-20251001",
"summary": "Extract Q1 income figures",
"cost_usd": 0.00071,
"latency_ms": 192,
"sources_summarized": ["/docs/finance/balance_sheet.md"],
"provenance_preserved": true
}
]
}
```

Test plan

• 16 new tests, 296 total passing
• Layer 2: factual_accuracy from checks (perfect / zero floor / partial credit / mixed / wrong value), judge prompt includes/omits section based on expected_facts presence, every expected fact rendered in the prompt, weighted score derives factual_accuracy when judge omits it, judge's numeric score takes priority when present, no derivation without signal
• Layer 3: helper_call appends to rollup, rollup omits sources_summarized for sources-less helpers, agent.call() embeds rollup in log record, rollup resets between calls
• All prior 280 tests still passing — no regressions

Notes

• Layer 3 here is the plumbing layer: it captures helper provenance automatically. The fuller spec/13 Layer 3 includes `sources_consulted` and `claims_in_response` fields that depend on the agent itself emitting them in its response (via fenced JSON or tool call) — the framework can pass them through, but populating them is an agent-side responsibility (the agent has to actually structure its output that way). This PR provides the helper-provenance side of Layer 3; the response-emission side is documented in spec/13 and is an authoring pattern, not a framework feature.
• This closes the last open spec-deferral issue. The full v0.x build sequence ([v0.2] Eval runner — atomic_agents.eval #1 eval, [v0.3] Tuning analyzer — atomic_agents.tuning #2 tuning, [v0.4] Goal manager — atomic_agents.goal #3 goal, [v0.5] Schema migration runner — atomic_agents.migrate #4 migrate, [v0.6] Tool-call captures (Path 1) — atomic_agents._capture #5 tool-call captures, [v0.7] Multi-agent project cascade loader — atomic_agents.agent #6 cascade, [v0.8] Helper provenance preservation #7 helper provenance, [v0.9] Research integrity Layers 2 + 3 #8 research integrity) is now landed.

🤖 Generated with Claude Code