Council Review: Phase 3 Retrieval Warning Propagation

Decision

Ship Phase 3 as a warning/provenance propagation layer that adds diagnostics and provider metadata to retrieval outputs without changing ranking, RRF fusion, temporal decay, persisted schemas, or agent-write behavior.

Evidence Reviewed

Findings

Seat Recommendation Confidence Blocking Concern
Source-Grounded Archivist Approve with documentation because diagnostics now travel with retrieval records and structured envelopes preserve source evidence for agents. 0.92 None blocking; keep envelope schema version explicit.
Data Model Architect Approve because the retrieval envelope is additive and not a persisted memory schema migration. 0.90 Default unified search response gains provider/diagnostic fields; this is additive but should stay documented.
Retrieval Specialist Approve because rank calculation paths remain unchanged while metadata exposes lexical, ONNX, token fallback, and hybrid provenance. 0.88 Watch envelope size and duplicate diagnostic text in future phases.
Human Learning Advocate Approve because chat reference warnings make stale/source/tag/relation problems visible at the point of use. 0.87 UI only surfaces compact chips; detailed remediation still depends on memory editor/governance pages.
Skeptical Reviewer Approve after validation because MCP and chat tool structured JSON are opt-in and Markdown defaults remain compatible. 0.84 Future clients may rely on exact unified-search JSON shape; additive defaults need release-note visibility.
Synthesizer Ship Phase 3 and move Phase 4 to context-planner/tool-registry work. 0.89 None blocking after local validation.

Synthesis

Phase 3 should merge as an additive retrieval transparency release. The implementation keeps current human-readable Markdown defaults for existing tool callers while allowing agents to opt into memorysmith.retrieval-results.v1 envelopes. Memory and page APIs expose opt-in envelopes through format=envelope/format=json-v2, and MCP/chat tools expose structured JSON through format=json, format=envelope, or format=json-v2. Unified search now returns diagnostic and provider metadata directly because it is already a composite API surface.

Deferred to later phases: ranking quality changes, temporal scoring, RRF tuning, persisted schema changes, native provider tool-call registration, and agent write governance.

Dissent

The Skeptical Reviewer would prefer all default API response additions to be behind format flags. The counterargument is that unified search already returns mixed result objects, so additive diagnostics and provider fields improve provenance without breaking existing JSON property readers. The risk is accepted with documentation and tests.

Acceptance Criteria

Open Questions