Simplify transition_ticket to allow any status (remove

Home Epics Simplify transition_ticket to allow any status (remove finalize_task)Edit

Simplify transition_ticket to allow any status (remove finalize_task)

Cancel

Title *

Project *

Description

## Problem

The current workflow has multiple transition events (`start_work`, `submit_review`, `complete`, `pass_audit`, `fail_audit`, `approve`, `reject`) plus a separate `finalize_task` action. This creates:

- Confusion about which action to use
- Redundant code paths
- Complex state machine with many transitions
- `finalize_task` only works from specific statuses (not `backlog`)

## Solution

Allow `transition_ticket` to accept any target status directly. The action becomes:

```
transition_ticket(ticket_id, status: "done")
```

Instead of the current complex workflow:
```
start_work → complete → pass_audit → approve (4 steps)
```

## Changes Required

### 1. Update MCP tool (`app/controllers/api/v1/mcp_controller.rb`)

**Change `handle_transition_ticket`:**
- Accept `status` parameter (any valid status) instead of `event`
- Remove `event` parameter entirely
- Validate target status is in the allowed list
- Use AASM's `fire_state_transition` or manual status update

**Before:**
```ruby
def handle_transition_ticket(ticket_id, event)
  ticket = Ticket.find(ticket_id)
  ticket.send("#{event}!")
  render json: ticket
end
```

**After:**
```ruby
def handle_transition_ticket(ticket_id, status)
  ticket = Ticket.find(ticket_id)
  allowed_statuses = Ticket.aasm.states.map(&:to_s)
  raise ArgumentError, "Invalid status: #{status}" unless allowed_statuses.include?(status)
  
  ticket.update!(status: status)
  render json: ticket
end
```

### 2. Remove `finalize_task`

**From MCP bridge** (`mcp-bridge/src/tools/index.ts`):
- Delete `finalize_task` tool entry

**From API** (if separate endpoint exists):
- Remove endpoint/controller method

### 3. Simplify AASM (keep events/guards, remove from→to restrictions)

**In** `app/models/ticket.rb`:

Keep AASM for before/after callbacks and guards, but allow any-to-any transitions:

```ruby
aasm column: :status do
  # Remove all specific event/transition declarations
  # Keep only state definitions and callbacks
  
  state :backlog, initial: true
  state :todo
  state :in_progress
  state :pending_audit
  state :pending_approval
  state :done
  state :blocked
  state :canceled
  
  # Keep before/after callbacks
  before_all_transactions :log_status_change
  
  # Remove all: event :start_work, event :submit_review, etc.
end
```

**Alternative:** If callbacks need to stay event-based, add a catch-all transition method that bypasses from→to validation.

### 4. Update documentation

**Update** `/rails/agents.rb`:
- Remove workflow references to specific events
- Update to show direct status transitions
- Remove `finalize_task` from tool lists

**Old:**
```
Worker:
  1. start_work
  2. [implement]
  3. complete
  4. submit_review
```

**New:**
```
Worker:
  1. transition_ticket(ticket_id, status: "in_progress")
  2. [implement]
  3. transition_ticket(ticket_id, status: "pending_audit")
```

### 5. Update tests

**Update** `spec/requests/api/v1/mcp_spec.rb`:
- Change tests from `event: "start_work"` to `status: "in_progress"`
- Add tests for direct any-to-any transitions
- Remove tests for removed events
- Remove `finalize_task` tests

## New Workflow Examples

```ruby
# Worker picks up work
transition_ticket(ticket_id, status: "in_progress")

# Worker submits for review
transition_ticket(ticket_id, status: "pending_audit")

# Orchestrator approves epic directly
transition_ticket(ticket_id, status: "done")

# Orchestrator moves from backlog to todo
transition_ticket(ticket_id, status: "todo")
```

## Acceptance Criteria

- `transition_ticket` accepts any valid status directly
- No `from`→`to` restrictions in state machine
- AASM callbacks still fire on status changes
- `finalize_task` removed from MCP tools
- Documentation updated with simplified workflow
- Tests pass (updated for new interface)

## Type

task / refactor

## Priority

medium