# Design: Move Jira to In Progress when Agent Nova starts a run

**Date:** 2026-09-15  
**Status:** Approved for implementation (Approach 1)

## Goal

Whenever Agent Nova creates a new run for a Jira ticket, transition that issue’s board status to **In Progress** so the board reflects that work has been accepted.

## Decisions

| Topic | Choice |
|-------|--------|
| When | Immediately after `create_run` succeeds (queued / accepted), before enqueue |
| Source status | Any current status — attempt transition if Jira exposes it |
| Target status | Configurable; default `"In Progress"` (`JIRA_IN_PROGRESS_STATUS`) |
| On failure | Log + audit; continue the run (do not fail webhook or enqueue) |
| Placement | Webhook path in `apps/api/app.py` (Approach 1) |

## Architecture

```
POST /webhooks/jira
  → should_start_run
  → create_run(...)
  → try: jira.transition_issue(key, settings.jira_in_progress_status)
       audit jira.transition / jira.transition_failed
  → enqueue_process_run(...)
```

### Components

1. **`Settings.jira_in_progress_status`** — env `JIRA_IN_PROGRESS_STATUS`, default `"In Progress"`.
2. **`JiraClient.transition_issue(key, target_status_name) -> bool`**
   - `HttpJiraClient`: GET `/rest/api/3/issue/{key}/transitions`, match transition by `to.name` (case-insensitive), POST that transition id. Return `True` if already at target or transition applied; `False` if no matching transition.
   - `MockJiraClient`: if already at target, no-op success; else set `issue.status` and record the transition.
3. **Webhook handler** — after `create_run`, call transition inside try/except; write `AuditEvent` (`jira.transition` or `jira.transition_failed`); never raise into the start path.

## Error handling

- Missing transition, HTTP errors, permissions → catch, audit with error detail, continue.
- Already **In Progress** → success / no-op (idempotent).
- Resume paths (clarification / design review) → **no** transition (only new run creation).

## Testing

- API webhook start: mock issue status becomes `In Progress`; audit event recorded.
- Transition failure (e.g. mock raises / no transition): run still queued.
- Resume / duplicate deliveries do not re-transition unnecessarily (only on new `create_run`).

## Out of scope

- Transitioning to Done / other terminal statuses
- Changing start gates (`Ready for Agent` / `agent-nova` label)
- Moving the transition into the orchestrator `ANALYZING` node