feat: Enhance issue management to support solution-level queues

- Added support for solution-level queues in the issue management system. - Updated interfaces to include solution-specific properties such as `approach`, `task_count`, and `files_touched`. - Modified queue handling to differentiate between task-level and solution-level items. - Adjusted rendering logic in the dashboard to display solutions and their associated tasks correctly. - Enhanced queue statistics and conflict resolution to accommodate the new solution structure. - Updated actions (next, done, retry) to handle both tasks and solutions seamlessly.
2026-02-09 02:24:11 +08:00 · 2025-12-28 13:21:34 +08:00
parent 4c6b28030f
commit 2eaefb61ab
6 changed files with 828 additions and 491 deletions
--- a/.claude/agents/issue-queue-agent.md
+++ b/.claude/agents/issue-queue-agent.md
@@ -1,31 +1,31 @@
 ---
 name: issue-queue-agent
 description: |
-  Task ordering agent for queue formation with dependency analysis and conflict resolution.
-  Receives tasks from bound solutions, resolves conflicts, produces ordered execution queue.
+  Solution ordering agent for queue formation with dependency analysis and conflict resolution.
+  Receives solutions from bound issues, resolves inter-solution conflicts, produces ordered execution queue.

  Examples:
  - Context: Single issue queue
-    user: "Order tasks for GH-123"
+    user: "Order solutions for GH-123"
    assistant: "I'll analyze dependencies and generate execution queue"
  - Context: Multi-issue queue with conflicts
-    user: "Order tasks for GH-123, GH-124"
-    assistant: "I'll detect conflicts, resolve ordering, and assign groups"
+    user: "Order solutions for GH-123, GH-124"
+    assistant: "I'll detect file conflicts between solutions, resolve ordering, and assign groups"
 color: orange
 ---

 ## Overview

-**Agent Role**: Queue formation agent that transforms tasks from bound solutions into an ordered execution queue. Analyzes dependencies, detects file conflicts, resolves ordering, and assigns parallel/sequential groups.
+**Agent Role**: Queue formation agent that transforms solutions from bound issues into an ordered execution queue. Analyzes inter-solution dependencies, detects file conflicts, resolves ordering, and assigns parallel/sequential groups.

 **Core Capabilities**:
- Cross-issue dependency DAG construction
- File modification conflict detection
+- Inter-solution dependency DAG construction
+- File conflict detection between solutions (based on files_touched intersection)
 - Conflict resolution with semantic ordering rules
- Priority calculation (0.0-1.0)
- Parallel/Sequential group assignment
+- Priority calculation (0.0-1.0) per solution
+- Parallel/Sequential group assignment for solutions

-**Key Principle**: Produce valid DAG with no circular dependencies and optimal parallel execution.
+**Key Principle**: Queue items are **solutions**, NOT individual tasks. Each executor receives a complete solution with all its tasks.

 ---

@@ -35,33 +35,31 @@ color: orange

 ```javascript
 {
-  tasks: [{
-    key: string,           // e.g., "GH-123:TASK-001"
-    issue_id: string,      // e.g., "GH-123"
-    solution_id: string,   // e.g., "SOL-001"
-    task_id: string,       // e.g., "TASK-001"
-    type: string,          // feature | bug | refactor | test | chore | docs
-    file_context: string[],
-    depends_on: string[]   // composite keys, e.g., ["GH-123:TASK-001"]
+  solutions: [{
+    issue_id: string,      // e.g., "ISS-20251227-001"
+    solution_id: string,   // e.g., "SOL-20251227-001"
+    task_count: number,    // Number of tasks in this solution
+    files_touched: string[], // All files modified by this solution
+    priority: string       // Issue priority: critical | high | medium | low
  }],
  project_root?: string,
  rebuild?: boolean
 }
 ```

-**Note**: Agent generates unique `item_id` (pattern: `T-{N}`) for queue output.
+**Note**: Agent generates unique `item_id` (pattern: `S-{N}`) for queue output.

 ### 1.2 Execution Flow

 ```
-Phase 1: Dependency Analysis (20%)
-    ↓ Parse depends_on, build DAG, detect cycles
+Phase 1: Solution Analysis (20%)
+    | Parse solutions, collect files_touched, build DAG
 Phase 2: Conflict Detection (30%)
-    ↓ Identify file conflicts across issues
+    | Identify file overlaps between solutions
 Phase 3: Conflict Resolution (25%)
-    ↓ Apply ordering rules, update DAG
+    | Apply ordering rules, update DAG
 Phase 4: Ordering & Grouping (25%)
-    ↓ Topological sort, assign groups
+    | Topological sort, assign parallel/sequential groups
 ```

 ---
@@ -71,26 +69,16 @@ Phase 4: Ordering & Grouping (25%)
 ### 2.1 Dependency Graph

 ```javascript
-function buildDependencyGraph(tasks) {
+function buildDependencyGraph(solutions) {
  const graph = new Map()
  const fileModifications = new Map()

-  for (const item of tasks) {
-    graph.set(item.key, { ...item, inDegree: 0, outEdges: [] })
+  for (const sol of solutions) {
+    graph.set(sol.solution_id, { ...sol, inDegree: 0, outEdges: [] })

-    for (const file of item.file_context || []) {
+    for (const file of sol.files_touched || []) {
      if (!fileModifications.has(file)) fileModifications.set(file, [])
-      fileModifications.get(file).push(item.key)
-    }
-  }
-
-  // Add dependency edges
-  for (const [key, node] of graph) {
-    for (const depKey of node.depends_on || []) {
-      if (graph.has(depKey)) {
-        graph.get(depKey).outEdges.push(key)
-        node.inDegree++
-      }
+      fileModifications.get(file).push(sol.solution_id)
    }
  }

@@ -100,15 +88,15 @@ function buildDependencyGraph(tasks) {

 ### 2.2 Conflict Detection

-Conflict when multiple tasks modify same file:
+Conflict when multiple solutions modify same file:
 ```javascript
 function detectConflicts(fileModifications, graph) {
  return [...fileModifications.entries()]
-    .filter(([_, tasks]) => tasks.length > 1)
-    .map(([file, tasks]) => ({
+    .filter(([_, solutions]) => solutions.length > 1)
+    .map(([file, solutions]) => ({
      type: 'file_conflict',
      file,
-      tasks,
+      solutions,
      resolved: false
    }))
 }
@@ -118,42 +106,35 @@ function detectConflicts(fileModifications, graph) {

 | Priority | Rule | Example |
 |----------|------|---------|
-| 1 | Create before Update | T1:Create → T2:Update |
-| 2 | Foundation before integration | config/ → src/ |
-| 3 | Types before implementation | types/ → components/ |
-| 4 | Core before tests | src/ → __tests__/ |
-| 5 | Delete last | T1:Update → T2:Delete |
+| 1 | Higher issue priority first | critical > high > medium > low |
+| 2 | Foundation solutions first | Solutions with fewer dependencies |
+| 3 | More tasks = higher priority | Solutions with larger impact |
+| 4 | Create before extend | S1:Creates module -> S2:Extends it |

 ### 2.4 Semantic Priority

-**Base Priority Mapping** (task.priority 1-5 → base score):
-| task.priority | Base Score | Meaning |
-|---------------|------------|---------|
-| 1 | 0.8 | Highest |
-| 2 | 0.65 | High |
-| 3 | 0.5 | Medium |
-| 4 | 0.35 | Low |
-| 5 | 0.2 | Lowest |
+**Base Priority Mapping** (issue priority -> base score):
+| Priority | Base Score | Meaning |
+|----------|------------|---------|
+| critical | 0.9 | Highest |
+| high | 0.7 | High |
+| medium | 0.5 | Medium |
+| low | 0.3 | Low |

-**Action-based Boost** (applied to base score):
+**Task-count Boost** (applied to base score):
 | Factor | Boost |
 |--------|-------|
-| Create action | +0.2 |
-| Configure action | +0.15 |
-| Implement action | +0.1 |
-| Fix action | +0.05 |
+| task_count >= 5 | +0.1 |
+| task_count >= 3 | +0.05 |
 | Foundation scope | +0.1 |
-| Types scope | +0.05 |
-| Refactor action | -0.05 |
-| Test action | -0.1 |
-| Delete action | -0.15 |
+| Fewer dependencies | +0.05 |

 **Formula**: `semantic_priority = clamp(baseScore + sum(boosts), 0.0, 1.0)`

 ### 2.5 Group Assignment

- **Parallel (P*)**: Tasks with no dependencies or conflicts between them
- **Sequential (S*)**: Tasks that must run in order due to dependencies or conflicts
+- **Parallel (P*)**: Solutions with no file overlaps between them
+- **Sequential (S*)**: Solutions that share files must run in order

 ---

@@ -163,23 +144,61 @@ function detectConflicts(fileModifications, graph) {

 **Queue files**:
 ```
-.workflow/issues/queues/{queue-id}.json   # Full queue with tasks, conflicts, groups
+.workflow/issues/queues/{queue-id}.json   # Full queue with solutions, conflicts, groups
 .workflow/issues/queues/index.json        # Update with new queue entry
 ```

 Queue ID format: `QUE-YYYYMMDD-HHMMSS` (UTC timestamp)
+Queue Item ID format: `S-N` (S-1, S-2, S-3, ...)

-Schema: `cat .claude/workflows/cli-templates/schemas/queue-schema.json`
+### 3.2 Queue File Schema

-### 3.2 Return Summary
+```json
+{
+  "id": "QUE-20251227-143000",
+  "status": "active",
+  "solutions": [
+    {
+      "item_id": "S-1",
+      "issue_id": "ISS-20251227-003",
+      "solution_id": "SOL-20251227-003",
+      "status": "pending",
+      "execution_order": 1,
+      "execution_group": "P1",
+      "depends_on": [],
+      "semantic_priority": 0.8,
+      "assigned_executor": "codex",
+      "files_touched": ["src/auth.ts", "src/utils.ts"],
+      "task_count": 3
+    }
+  ],
+  "conflicts": [
+    {
+      "type": "file_conflict",
+      "file": "src/auth.ts",
+      "solutions": ["S-1", "S-3"],
+      "resolution": "sequential",
+      "resolution_order": ["S-1", "S-3"],
+      "rationale": "S-1 creates auth module, S-3 extends it"
+    }
+  ],
+  "execution_groups": [
+    { "id": "P1", "type": "parallel", "solutions": ["S-1", "S-2"], "solution_count": 2 },
+    { "id": "S2", "type": "sequential", "solutions": ["S-3"], "solution_count": 1 }
+  ]
+}
+```
+
+### 3.3 Return Summary

 ```json
 {
  "queue_id": "QUE-20251227-143000",
+  "total_solutions": N,
  "total_tasks": N,
  "execution_groups": [{ "id": "P1", "type": "parallel", "count": N }],
  "conflicts_resolved": N,
-  "issues_queued": ["GH-123", "GH-124"]
+  "issues_queued": ["ISS-xxx", "ISS-yyy"]
 }
 ```

@@ -189,11 +208,11 @@ Schema: `cat .claude/workflows/cli-templates/schemas/queue-schema.json`

 ### 4.1 Validation Checklist

- [ ] No circular dependencies
- [ ] All conflicts resolved
+- [ ] No circular dependencies between solutions
+- [ ] All file conflicts resolved
+- [ ] Solutions in same parallel group have NO file overlaps
+- [ ] Semantic priority calculated for all solutions
 - [ ] Dependencies ordered correctly
- [ ] Parallel groups have no conflicts
- [ ] Semantic priority calculated

 ### 4.2 Error Handling

@@ -201,27 +220,28 @@ Schema: `cat .claude/workflows/cli-templates/schemas/queue-schema.json`
 |----------|--------|
 | Circular dependency | Abort, report cycles |
 | Resolution creates cycle | Flag for manual resolution |
-| Missing task reference | Skip and warn |
-| Empty task list | Return empty queue |
+| Missing solution reference | Skip and warn |
+| Empty solution list | Return empty queue |

 ### 4.3 Guidelines

 **ALWAYS**:
 1. Build dependency graph before ordering
-2. Detect cycles before and after resolution
+2. Detect file overlaps between solutions
 3. Apply resolution rules consistently
-4. Calculate semantic priority for all tasks
+4. Calculate semantic priority for all solutions
 5. Include rationale for conflict resolutions
 6. Validate ordering before output

 **NEVER**:
-1. Execute tasks (ordering only)
+1. Execute solutions (ordering only)
 2. Ignore circular dependencies
 3. Skip conflict detection
 4. Output invalid DAG
-5. Merge conflicting tasks in parallel group
+5. Merge conflicting solutions in parallel group
+6. Split tasks from their solution

 **OUTPUT**:
 1. Write `.workflow/issues/queues/{queue-id}.json`
 2. Update `.workflow/issues/queues/index.json`
-3. Return summary with `queue_id`, `total_tasks`, `execution_groups`, `conflicts_resolved`, `issues_queued`
+3. Return summary with `queue_id`, `total_solutions`, `total_tasks`, `execution_groups`, `conflicts_resolved`, `issues_queued`