v0.2.0 — The AI narrative layer

Whydunit v0.2.0 — The AI narrative layer

v0.1 diagnosed pipeline failures deterministically. v0.2 adds an LLM that
explains those findings — with zero authority.

What's new

• whydunit.explain — an optional narrative layer over the case file:
  • The model is shown only the leading hypothesis and its evidence,
    with stable IDs, and must cite an ID for every factual claim.
  • A deterministic citation validator parses every narrative and
    refuses any that cites an unknown ID or makes an uncited claim —
    one corrective retry, then refusal. Invalid narratives are never shown.
  • Alternative hypotheses are appended by code, labelled
    machine-written — the model never sees them, so it cannot misstate them.
• CLI: python -m whydunit.explain --scenario retrieval_degradation --seed 42
• Console: "AI narrative report" panel on the Notes & Case File page,
  plus scenario-qualified export filenames.
• Optional dependency: uv sync --extra llm + ANTHROPIC_API_KEY. The
  core remains fully offline and LLM-free; CI runs without a key
  (explain tests use a stubbed client).

The design that survived contact

During development the validator refused three narratives — invented ID
formats, uncited scene-setting, uncited summaries of lower-ranked
hypotheses. The third was fixed structurally, not by prompt tuning: the
model no longer sees the alternatives at all. Every refusal was the
system working; none of those narratives reached a user. Full story:
docs/narrative-layer.md

Unchanged

12/12 top-1 diagnostic accuracy, 0 FP / 0 FN, ground-truth firewall
enforced by test. 158 tests passing, ruff clean, CI green on
ubuntu/windows × py3.12/3.13.

MIT licensed.