[shivros]

Summary

Adds the four-artifact add-retained-history successor OpenSpec contract for COD-544. It resolves the frozen ingested-inbox pagination conflict in favor of durable store-scoped retained history, defines the normal generated v2 HTTP/CLI/MCP reader compatibility boundary, and specifies cross-process snapshot cursors, identity/order, honest coverage, attachment ownership, and producer handoffs.

Scope

• proposal.md, design.md, tasks.md, and specs/retained-history/spec.md only.
• Existing add-ingested-inbox, add-forward-poll-cursors, and add-sse-replay-cursors artifacts are unchanged.
• No Rust, generated artifact, dependency, migration, credential/auth policy, encryption, deployment, release, or live-provider behavior changed.
• Future runtime work is split into explicit file-level, dependency-ordered tasks; inbound acquisition, COD-475 outbound capture, COD-493 auth, COD-494 publication, and COD-543 encryption remain separate owners.

Verification

• git diff --check — passed.
• Structural contract check — passed: 4 required files, 7 requirements, 16 scenarios, 15 unchecked implementation/verification tasks, and 7 deterministic fixture UUIDs verified.
• Frozen sibling OpenSpec diff check — unchanged.
• openspec validate add-retained-history --strict — unavailable in the hosted runner (openspec command not installed); structural fallback was run and recorded.
• Cargo/runtime gates are not applicable because this PR changes no Rust or generated/runtime artifact.

Review boundary

This is a contract/specification gate and requires manual review before implementation work proceeds. Do not merge automatically; runtime tasks remain unchecked until this successor is approved.

Linear: COD-544

[shivros]

🤖 Automated Review Panel

Reviewer A — delegate_task contract review

Verdict: APPROVE

• Blocking findings: none.
• Non-blocking findings: none based on the supplied task, project context, and diff summary.

The proposed storage-first v2 boundary, explicit compatibility transition, durable cursor policy, producer ownership split, and runtime guardrails align with the goal.

Reviewer B — Gemini 3 Flash via OpenRouter

Verdict: APPROVE

• Blocking findings: none.
• The contract correctly requires zero provider I/O for retained queries, explicitly supersedes the conflicting frozen first-reader paragraphs, and uses durable store-scoped cursors with explicit 15-minute expiry and 1,024-token capacity.
• Identity is collision-isolated by (source, installation_id) and stable session/occurrence values; ordering includes configured instance identity where needed; coverage distinguishes complete, partial, and not-acquired history.
• Non-blocking observations: monitor cursor-eviction rates in COD-492 runtime tests; ensure implementation uses the specified length-prefixed production identity encoding rather than the fixture-only UUID form; and prove storage snapshot isolation/pinning so mutation during continuation cannot cause phantom reads.

Both reviewers found no correctness or goal-alignment blocker. Runtime implementation remains gated on this contract's manual review and merge.