feat(maniphest): Add Priority Filtering and Restructure Task Output

[Timpan4]

Overview

This PR adds comprehensive priority-based filtering for Maniphest tasks and restructures the output format to provide clearer separation between current state, history, and filter metadata.

Key Features

🎯 Priority Filtering

Filter tasks based on priority changes over time, complementing the existing column transition filtering.

Supported patterns:

• from:PRIORITY[:direction] - Task changed from a priority (optionally with raised/lowered direction)
• to:PRIORITY - Task changed to a priority
• in:PRIORITY - Task is currently at a priority
• been:PRIORITY - Task was at a priority at any point in history
• never:PRIORITY - Task was never at a priority
• raised - Task had any priority increase
• lowered - Task had any priority decrease

Examples:

# Find tasks that were escalated to "Unbreak Now!" from Normal priority
phabfive maniphest search "My Project" --priority="from:Normal:raised"

# Find tasks currently at High priority
phabfive maniphest search "My Project" --priority="in:High"

# Find tasks that were ever at "Unbreak Now!" priority
phabfive maniphest search "My Project" --priority="been:Unbreak Now!"

# Combine with column filters - tasks moved forward from "Up Next" that were at Normal
phabfive maniphest search '*' \
  --column='from:Up Next:forward' \
  --priority='been:Normal' \
  --show-history \
  --show-metadata

📊 Restructured Output Format

The task output is now organized into three clear sections:

1. Task - Current state snapshot

Task:
  Name: '[FEATURE] Improved error diagnostics'
  Created: 2025-10-01T17:21:56
  Modified: 2025-10-24T08:44:53
  Status: Open
  Priority: Unbreak Now!
  Description: |
    > Enhanced error reporting
  Boards:
    Development:
      Column: Up Next
    GUNNAR-Core:
      Column: In Review

2. History - Transition timeline (only shown with --show-history)

History:
  Priority:
    - "2025-10-01T17:21:56 [↓] Triage → Normal"
    - "2025-10-23T12:55:59 [↑] Normal → Unbreak Now!"
  Boards:
    Development:
      Transitions:
        - "2025-10-14T10:52:33 [→] Backlog → In Review"
        - "2025-10-14T14:31:40 [←] In Review → Up Next"

3. Metadata - Filter match information (only shown with --show-metadata)

Metadata:
  MatchedBoards: ['Development', 'GUNNAR-Core']
  MatchedPriority: true

🔍 Filter Debugging with --show-metadata

New flag to help debug complex filter combinations by showing exactly which boards and priorities matched your filters.

phabfive maniphest search '*' \
  --column='from:Up Next:forward' \
  --priority='been:Normal' \
  --show-metadata

This shows:

• MatchedBoards: Which board(s) satisfied the --column filter
• MatchedPriority: Whether the task matched the --priority filter

🔄 Explicit History Display

History is now only shown when explicitly requested with --show-history, not auto-enabled by filters. This improves performance for quick filtering operations.

# Fast: Filter only, no history fetching
phabfive maniphest search "My Project" --column="in:Done"

# Detailed: Include transition history
phabfive maniphest search "My Project" --column="in:Done" --show-history

Technical Changes

New Files

• phabfive/priority_transitions.py - Priority filtering logic with pattern matching
• tests/test_priority_transitions.py - Comprehensive test suite (51 tests)

Modified Files

• phabfive/cli.py - Added --priority, --show-metadata flags; removed deprecated --show-transitions
• phabfive/maniphest.py - Restructured output, priority filtering integration, alphabetical board sorting
• docs/maniphest-cli.md - Comprehensive documentation for new features
• tests/test_maniphest.py - Updated for new method signatures

Breaking Changes

1. Removed --show-transitions flag (use --show-history instead)
2. History no longer auto-enabled - must explicitly use --show-history
3. Output format changed - Tasks now use nested Task/History/Metadata structure

Use Cases

Track Priority Escalations

# Find all tasks that were raised to Unbreak Now!
phabfive maniphest search '*' --priority='to:Unbreak Now!' --show-history

Audit Workflow Compliance

# Tasks completed without going through review
phabfive maniphest search "Product" \
  --column="in:Done+never:In Review" \
  --show-history

Debug Complex Filters

# See exactly why each task matched
phabfive maniphest search "Backend" \
  --column="from:In Progress:forward" \
  --priority="raised" \
  --show-metadata

Sprint Analysis

# High-priority tasks completed in last 14 days
phabfive maniphest search "Sprint 42" \
  --column="to:Done" \
  --priority="in:High,in:Unbreak Now!" \
  --updated-after=14 \
  --show-history

[holmboe]

LGTM