# Workflow Event-to-LangGraph Mapping

This document maps every `WorkflowEvent` enum member and every workflow in `WORKFLOW_REGISTRY`
to their LangGraph equivalents. Each row documents how a legacy event-driven transition
is represented in the LangGraph graph topology.

## Mapping Table

| Workflow | Event | Legacy From Step | Legacy To Step | LangGraph From Node | LangGraph To Node | Conditional Edge Function | Routing Signal Fields |
|----------|-------|-----------------|----------------|--------------------|--------------------|--------------------------|----------------------|
| work-on-jira-issue | JIRA_ISSUE_RETRIEVED | initiate | planning | initiate | planning | `route_after_initiate` | `issue_retrieved` |
| work-on-jira-issue | SETUP_COMPLETE | initiate | setup | initiate | setup | `route_after_initiate` | `needs_setup` |
| work-on-jira-issue | JIRA_COMMENT_ADDED | planning | checklist-creation | planning | checklist_creation | `route_after_plan` | `plan_posted` |
| work-on-jira-issue | MANUAL_ADVANCE | planning | checklist-creation | planning | checklist_creation | `route_after_plan` | `plan_posted` (automated; MANUAL_ADVANCE replaced by signal evaluation) |
| work-on-jira-issue | CHECKLIST_CREATED | checklist-creation | implementation | checklist_creation | implementation | `route_after_checklist_creation` | `checklist_created` |
| work-on-jira-issue | MANUAL_ADVANCE | checklist-creation | implementation | checklist_creation | implementation | `route_after_checklist_creation` | `checklist_created` (automated; MANUAL_ADVANCE replaced by signal evaluation) |
| work-on-jira-issue | CHECKLIST_COMPLETE | implementation | implementation-review | implementation | implementation_review | `route_after_implementation` | `checklist_complete` |
| work-on-jira-issue | MANUAL_ADVANCE | implementation-review | verification | implementation_review | verification | `route_after_implementation_review` | `verification_ready` |
| work-on-jira-issue | MANUAL_ADVANCE | implementation | verification | REMOVED | REMOVED | N/A — skip-review path not implemented in LangGraph; all `implementation` outputs route via `implementation_review` | N/A |
| work-on-jira-issue | MANUAL_ADVANCE | verification | commit | verification | commit | `route_after_verify` | `error` (absent), `retry_count` |
| work-on-jira-issue | GIT_COMMIT_CREATED | commit | pull-request | commit | pull_request | `route_after_commit` | `commit_created`, `branch_pushed` (both required) |
| work-on-jira-issue | GIT_BRANCH_PUSHED | commit | pull-request | commit | pull_request | `route_after_commit` | `commit_created`, `branch_pushed` (both required) |
| work-on-jira-issue | PR_CREATED | pull-request | completion | pull_request | completion | `route_after_pull_request` | `pr_created` |
| pull-request-review | MANUAL_ADVANCE | initiate | pr-synthesis | N/A — not yet implemented in LangGraph | N/A — not yet implemented in LangGraph | N/A | N/A |
| pull-request-review | MANUAL_ADVANCE | pr-synthesis | delegate | N/A — not yet implemented in LangGraph | N/A — not yet implemented in LangGraph | N/A | N/A |
| pull-request-review | MANUAL_ADVANCE | delegate | consolidate-and-submit | N/A — not yet implemented in LangGraph | N/A — not yet implemented in LangGraph | N/A | `all_complete` must be true; guard keeps step on `delegate` when false |
| pull-request-review | MANUAL_ADVANCE | consolidate-and-submit | decision | N/A — not yet implemented in LangGraph | N/A — not yet implemented in LangGraph | N/A | N/A |
| pull-request-review | MANUAL_ADVANCE | decision | completion | N/A — not yet implemented in LangGraph | N/A — not yet implemented in LangGraph | N/A | N/A |
| pr-merge-orchestrator | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented |
| work-on-jira-issue | JIRA_ISSUE_CREATED | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented |
| work-on-jira-issue | JIRA_ISSUE_UPDATED | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented |
| work-on-jira-issue | PR_APPROVED | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented |
| work-on-jira-issue | PR_REVIEWED | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented |
| work-on-jira-issue | PR_MERGE_POLL | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented |
| work-on-jira-issue | PR_MERGED | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented | N/A — not yet implemented |

## Design Decisions

### Events → Conditional Edges

Instead of emitting events post-execution, each node sets state fields that conditional
edge functions evaluate. For example:

- `planning_node` sets `plan_posted=True` → `route_after_plan` routes to `checklist_creation`
- `commit_node` sets `commit_created=True` and `branch_pushed=True` → `route_after_commit` routes to `pull_request`

### Background Task Waiting → Synchronous Node Execution

Background tasks (git push, API calls) are absorbed into node execution. Nodes execute
synchronously — the graph blocks until the node completes. This is simpler than async
polling and sufficient for the current use case.

### Auto-Advancement → Sequential/Conditional Edges

Most auto-advance transitions map to either:

- Sequential edges (A → B) for unconditional advancement
- Conditional edges (A → [B or C]) for state-dependent routing

### Manual Advancement → REMOVED

`MANUAL_ADVANCE` in the mapping table is the *legacy event name* — these transitions
previously required a human to call `advance_workflow` to trigger the next step (or an
`interrupt()` pause in LangGraph). In the current implementation __all of those
transitions are fully automated__: the corresponding LangGraph conditional edge function
evaluates a routing signal field (`verification_ready`, `checklist_complete`, etc.) and
advances the graph without any human intervention or `interrupt()` call. The legacy event
name is retained in the table only for traceability back to the original event-driven
design.

### Error Handling → Shared `error_handler` Node

A single `error_handler` node serves as the terminal for unrecoverable errors.
All conditional edge functions check `state.get("error")` first and route to
`error_handler` when an error is present.

### Legacy Checkpoint Compatibility

When routing signal fields are absent from state (pre-refactor checkpoints), routing
functions fall back to the previous default successor rather than routing to
`error_handler`. This preserves backward compatibility with existing checkpoint data.
