Add idempotent retrospectives for terminal workflow outcomes

[eshulman2]

Problem

Forge records workflow timing, model usage, CI repair, review cycles, blocked reasons, and post-merge summaries, but it does not systematically turn terminal workflow evidence into improvement recommendations.

Forge workflows are event-driven and resumable. Waiting for human approval/review is not terminal, and a ticket that was blocked may later be retried. A retrospective must therefore attach to the worker's lifecycle boundary without changing LangGraph routing or turning a resumable state into permanent completion.

Forge architecture boundary

• Workflow graphs produce and checkpoint delivery state.
• The worker determines whether processing reached a genuine terminal outcome.
• Retrospective generation runs after that outcome and cannot modify it.
• Jira publication is an optional side effect after the report is persisted.
• Automatic improvement-ticket creation is a separately enabled, deduplicated action.

Proposed solution

Add an opt-in retrospective service invoked by the worker for centrally defined terminal outcomes.

The initial analyzer should be deterministic and consume a typed, bounded, redacted evidence summary. A future model-backed analyzer can implement the same interface behind separate configuration.

Evidence may include:

• workflow type and terminal outcome
• elapsed time and step timing summaries
• bounded retry, CI-repair, and review-cycle counts
• blocked/error categories with redacted messages
• model token/cost summaries
• trace/artifact references rather than raw logs

Lifecycle and idempotency

• Human/approval/review waiting states are never terminal.
• Retrospective failure never changes the workflow outcome or acknowledgement behavior.
• Use a stable idempotency key derived from workflow/thread identity, terminal outcome generation, and retrospective schema/analyzer version.
• Worker restart or duplicate delivery must not duplicate reports.
• A later explicit retry that reaches a new terminal outcome may produce a new retrospective generation.

Acceptance criteria

• Terminal outcomes are defined centrally and tested; waiting/resumable states are excluded.
• Retrospective input and output use versioned typed models.
• Evidence is bounded and redacted before analysis or persistence.
• The initial deterministic analyzer records zero model tokens/cost and produces evidence-linked recommendations.
• Retrospective execution is opt-in, non-blocking, and cannot alter the completed workflow state.
• Idempotency survives duplicate events and worker restart.
• Explicit retry followed by a new terminal outcome can create a distinct generation without duplicating the previous one.
• Jira report publication is optional.
• Improvement-ticket creation is disabled separately by default and deduplicated when enabled.
• Tests cover success, permanent failure, human-waiting, review-waiting, blocked/retried/successful, duplicate event, restart, and retrospective service failure.

Estimate

AI-assisted: 4–7 engineering days.