photoanalyzer/delivery_backlog/stories/US03-03-proposal-generation.md

US03-03 — Generate and Persist Versioned Proposals

Epic: E03

As a user, I want AI-assisted album proposals with rationale and confidence so I can evaluate suggestions before approving them.

Acceptance criteria

• A provider adapter receives only the minimum aggregated evidence and returns a validated structured proposal.
• Proposal, evidence version, model/prompt version, rationale, confidence, edits, and approval state are durable.
• Malformed, rate-limited, failed, duplicate, and stale responses are explicit and safely retryable.
• Approval validates the latest proposal version and performs no rename.

Automated tests

• Deterministic fake-provider tests cover success, malformed output, retry, and failure.
• API tests cover creation, edits, optimistic conflicts, approval, and restart.

Dependencies

• US03-01, US03-02