feat(ai) Phase 4 W1-2 — tool-trace citation extraction (ADR-0022)

[jkeeley2073]

Summary

Phase 4 Wave 1 PR W1-2 — closes § Scope item 10 / inherited Phase 3 follow-up #5. Implements ADR-0022: citations come from the agent's tool-call result trace, not regex over the Wizard's outer prose.

New abstraction ICitationExtractor (Application/Ai/Citations/) with two impls:

• ToolTraceCitationExtractor — walks AgentResponse.Messages and extracts citations from FunctionResultContent instances. getMachineByTitle results produce structured citations from MachineGroundingDto.OpdbSourceUrl; connected sub-agent function results (Valuation/Rules/Repair from PR feat(ai) Phase 4 W1-1 — connected-agents wiring on Wizard via AsAIFunction #96 wiring) produce citations from OPDB URLs embedded in the sub-agent's text reply. The Wizard's outer assistant text is structurally unreachable by the extractor — hallucinated URLs in Wizard prose without backing tool-call results no longer count.

• RegexLegacyCitationExtractor — the Phase 3 regex impl, kept behind AiFoundryOptions.RetainRegexCitationCutover (default true) for the cutover observability window per ADR-0022 § Telemetry. Both extractors emit pinwiz.ai.citations.extracted_total{source=...} so a behavioral regression in the new tool-trace one would surface in metrics before H3 baseline. Counter, type, unit, and tag shape exactly match the ADR spec. After H2 confirms parity-or-better, RegexLegacyCitationExtractor + the cutover flag get deleted in a follow-up PR.

AiRouter refactored: inline ExtractCitationsFromText + OpdbMachineUrlRegex deleted; AiRouter is no longer partial; using System.Text.RegularExpressions removed. Both extractors are concrete-type-injected into AiRouter (the cutover semantics are asymmetric — tool-trace authoritative, regex_legacy telemetry-only).

This PR + W1-1 (PR #96) together address the two structural causes of Phase 3's H2 baseline citation_precision=0.133: connected-agents wiring (W1-1) made sub-agent grounding reachable, tool-trace extraction (W1-2) makes citations structurally tied to what the agent actually retrieved.

Test Plan

• dotnet build PinballWizard.slnx — Build succeeded, 0 Warning(s), 0 Error(s)
• dotnet test PinballWizard.slnx — Passed: 709, Failed: 0, Skipped: 0 (was 691; +18 new tests = 11 tool-trace + 6 regex-legacy + 1 cross-channel-dedup + 1 multi-FRC-in-message)
• Tool-trace tests cover: null response, no FRC, structured grounding DTO, null grounding, missing-OPDB-URL DTO, duplicate calls (same DTO twice), sub-agent text mining, mixed grounding+sub-agent (union), cross-channel dedup (DTO+text same URL), multiple FRC in single message, no-Wizard-prose-counted invariant (the headline behavior change vs. regex)
• Regex-legacy tests pin Phase 3 behavior so cutover comparison has a stable comparison point
• Live integration verification post-merge: H2 baseline rerun (operational hand-off) measures actual citation_precision lift from the new structural extractor

Out of Scope

• searchCorpus tool integration (Phase 4 scope item 21, separate PR — extends ToolTraceCitationExtractor symmetrically with RetrievedChunk[] results from RAG retrieval)
• Citation-required guardrail (ADR-0023, Phase 4 scope item 23 — depends on this extractor being structural; that PR uses citations.Count == 0 as the refusal trigger)
• Removal of RegexLegacyCitationExtractor and RetainRegexCitationCutover flag (deferred to a follow-up PR after H2 baseline confirms parity-or-better)

Checklist

• CI is green (build + test + coverage + CodeQL + sanitization) — verified pre-push; will re-confirm in PR checks
• PR title follows the Conventional Commits format above
• If this is a new architectural decision, an ADR has been added under docs/adr/ — implements ADR-0022 (already merged in Wave 0)
• If user-visible behavior changes, README.md and/or docs/ are updated in the same PR — citation extraction is internal mechanics; no user-visible change yet (the citation surface in WizardAnswer is unchanged)
• If a memory in ~/.claude/projects/c--projects-PinballWizard/memory/ is now stale, it has been updated or removed in the same PR — wave0_close handoff already references W1-2 as queued
• No TODO / FIXME / commented-out code committed
• No new entries in <NoWarn> without a comment explaining why and the removal criterion — N/A (no Directory.Build.props changes)

Pre-push self-audit

Step 0 — /local-review (qualitative)

• Ran /local-review and addressed every 🔴 finding before push
• Local review outcome: 0 🔴 / 2 ⚠️ (both fixed pre-push) / 12 categories ✅
  • Fixed: comment typo in RegexLegacyCitationExtractor.cs:8 referenced wrong property name
  • Fixed: added Extract_SameUrlInDtoAndSubAgentText_Deduplicates and Extract_MultipleFunctionResultsInSingleMessage_AllProcessed test-gap fills

Step 1 — Mechanical checklist

• Every new *Options property has at least one real getter call in src/ — RetainRegexCitationCutover is read at AiRouter.cs:179
• Sibling-diffed against the closest existing implementation — verified by /local-review § 4; RegexLegacyCitationExtractor preserves the prior inline implementation's behavior exactly so cutover comparison counts will be apples-to-apples
• No bare catch { } — no new try/catch added
• New ISourceScraper? — N/A
• Tests assert behavior, not just structure — every test exercises a specific ADR-0022 invariant or behavior (no-prose-counted, structured grounding, sub-agent text mining, cross-channel dedup, etc.)
• Build is zero-warning — verified
• git log -1 --format='%an <%ae>' shows personal noreply, not work email — confirmed 94459922+jkeeley2073@users.noreply.github.com